docs/generate_docs.pl

   1 #!/usr/bin/perl
   2 # ---------------------------------------------------------------
   3 # Copyright © 2020 MOBIUS
   4 # Blake Graham-Henderson <blake@mobiusconsortium.org>
   5 #
   6 # This program is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 # ---------------------------------------------------------------
  16
  17
  18 use Getopt::Long;
  19 use Cwd;
  20 use File::Path;
  21 use Data::Dumper;
  22
  23 my $base_url;
  24 my $tmp_space = './build';
  25 my $html_output = './output';
  26 my $antoraui_git = 'git://git.evergreen-ils.org/eg-antora.git';
  27 my $antoraui_git_branch = 'master';
  28 my $antora_version = '2.3';
  29 my $help;
  30
  31
  32
  33 GetOptions (
  34 "base-url=s" => \$base_url,
  35 "tmp-space=s" => \$tmp_space,
  36 "html-output=s" => \$html_output,
  37 "antora-ui-repo=s" => \$antoraui_git,
  38 "antora-ui-repo-branch=s" => \$antoraui_git_branch,
  39 "antora-version=s" => \$antora_version,
  40 "help" => \$help
  41 );
  42
  43 sub help
  44 {
  45     print <<HELP;
  46     $0
  47     --base-url http://example.com
  48     --tmp-space ../../tmp
  49     --html-output /var/www/html
  50     --antora-ui-repo git://git.evergreen-ils.org/eg-antora.git
  51     --antora-version 2.3
  52
  53     You must specify
  54     --base-url                                    [URL where html output is expected to be available eg: http//examplesite.org/docs]
  55     --tmp-space                                   [Writable path for staging the antora UI repo and build files, defaults to ./build]
  56     --html-output                                 [Path for the generated HTML files, defaults to ./output]
  57     --antora-ui-repo                              [Antora-UI repository for the built UI, defaults to git://git.evergreen-ils.org/eg-antora.git]
  58     --antora-ui-repo-branch                       [OPTIONAL: Antora-UI repository checkout branch, Defaults to "master"]
  59     --antora-version                              [Target version of antora, defaults to 2.3]
  60
  61 HELP
  62     exit;
  63 }
  64
  65 # Make sure the user supplied ALL of the options
  66 help() if(!$base_url || !$tmp_space || !$html_output || !$antoraui_git || !$antora_version);
  67
  68 # make sure the URL is "right"
  69 $base_url = lc ($base_url);
  70 $base_url =~ s/^[\s\t]*//g;
  71 $base_url =~ s/[\s\t]*$//g;
  72 if ( !($base_url =~ m/^https?:\/\/.+\..+$/))
  73 {
  74     print "Please specify a proper URL starting with http(s)\n";
  75     exit;
  76 }
  77
  78
  79 # deal with destination folders
  80 if (-d "$tmp_space/antora-ui") {
  81     print "cleaning $tmp_space/antora-ui/\n";
  82     rmtree("$tmp_space/antora-ui/");
  83 }
  84
  85 if (-d "$html_output") {
  86     print "cleaning $html_output/\n";
  87     rmtree("$html_output/");
  88 }
  89
  90 # make sure the temp folder is good
  91 mkdir $tmp_space unless ( -d $tmp_space );
  92
  93 # make sure the output folder is good
  94 mkdir $html_output unless ( -d $html_output );
  95
  96 die "Both " . $tmp_space . " and " . $html_output . " must be writable!" unless ( -w $tmp_space && -w $html_output );
  97
  98 # Deal with ui repo
  99 exec_system_cmd("git clone $antoraui_git $tmp_space/antora-ui");
 100
 101 exec_system_cmd("cd $tmp_space/antora-ui && git checkout $antoraui_git_branch");
 102
 103 exec_system_cmd("cd $tmp_space/antora-ui && npm install gulp-cli");
 104
 105 exec_system_cmd("cd $tmp_space/antora-ui && npm install");
 106
 107 exec_system_cmd("cd $tmp_space/antora-ui && ./node_modules/.bin/gulp build && ./node_modules/.bin/gulp pack");
 108
 109
 110 exec_system_cmd("cp site.yml site-working.yml");
 111
 112 # Deal with root URL Antora configuration
 113 rewrite_yml($base_url,"site/url","site-working.yml");
 114 rewrite_yml("$html_output","output/dir","site-working.yml");
 115 rewrite_yml("$tmp_space/antora-ui/build/ui-bundle.zip","ui/bundle/url","site-working.yml");
 116
 117 #npm install antora
 118 exec_system_cmd('npm install @antora/cli@' . $antora_version . ' @antora/site-generator-default@' . $antora_version . ' antora-lunr antora-site-generator-lunr');
 119
 120 # Now, finally, let's build the site
 121 exec_system_cmd('DOCSEARCH_INDEX_VERSION=latest DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm root)" ./node_modules/@antora/cli/bin/antora --generator antora-site-generator-lunr site-working.yml');
 122
 123 print "Success: your site files are available at " . $html_output . " and can be moved into place for access at " . $base_url . "\n";
 124
 125 sub rewrite_yml
 126 {
 127     my $replacement = shift;
 128     my $yml_path = shift;
 129     my $file = shift;
 130     my $contents = replace_yml($replacement,$yml_path,$file);
 131     $contents =~ s/[\n\t]*$//g;
 132     write_file($file, $contents) if ($contents =~ m/$replacement/);
 133 }
 134
 135 sub write_file
 136 {
 137     my $file = shift;
 138     my $contents = shift;
 139
 140         my $ret=1;
 141         open(OUTPUT, '> '.$file) or $ret=0;
 142         binmode(OUTPUT, ":utf8");
 143         print OUTPUT "$contents\n";
 144         close(OUTPUT);
 145         return $ret;
 146 }
 147
 148 sub replace_yml
 149 {
 150     my $replacement = shift;
 151     my $yml_path = shift;
 152     my $file = shift;
 153     my @path = split(/\//,$yml_path);
 154     my @lines = @{read_file($file)};
 155     my $depth = 0;
 156     my $ret = '';
 157     while(@lines[0])
 158     {
 159         my $line = shift @lines;
 160         if(@path[0])
 161         {
 162             my $preceed_space = $depth * 2;
 163             my $exp = '\s{'.$preceed_space.'}';
 164             $exp = '[^\s#]' if $preceed_space == 0;
 165             # print "testing $exp\n";
 166             if($line =~ m/^$exp.*/)
 167             {
 168                 if($line =~ m/^\s*@path[0].*/)
 169                 {
 170                     $depth++;
 171                     if(!@path[1])
 172                     {
 173                         # print "replacing '$line'\n";
 174                         my $t = @path[0];
 175                         $line =~ s/^(.*?$t[^\s]*).*$/\1 $replacement/g;
 176                         # print "now: '$line'\n";
 177                     }
 178                     shift @path;
 179                 }
 180             }
 181         }
 182         $line =~ s/[\n\t]*$//g;
 183         $ret .= "$line\n";
 184     }
 185
 186     return $ret;
 187 }
 188
 189 sub exec_system_cmd
 190 {
 191     my $cmd = shift;
 192     print "executing $cmd\n";
 193     system($cmd) == 0
 194         or die "system @args failed: $?";
 195 }
 196
 197 sub read_file
 198 {
 199         my $file = shift;
 200         my $trys=0;
 201         my $failed=0;
 202         my @lines;
 203         #print "Attempting open\n";
 204         if(-e $file)
 205         {
 206                 my $worked = open (inputfile, '< '. $file);
 207                 if(!$worked)
 208                 {
 209                         print "******************Failed to read file*************\n";
 210                 }
 211         binmode(inputfile, ":utf8");
 212                 while (!(open (inputfile, '< '. $file)) && $trys<100)
 213                 {
 214                         print "Trying again attempt $trys\n";
 215                         $trys++;
 216                         sleep(1);
 217                 }
 218                 if($trys<100)
 219                 {
 220                         #print "Finally worked... now reading\n";
 221                         @lines = <inputfile>;
 222                         close(inputfile);
 223                 }
 224                 else
 225                 {
 226                         print "Attempted $trys times. COULD NOT READ FILE: $file\n";
 227                 }
 228                 close(inputfile);
 229         }
 230         else
 231         {
 232                 print "File does not exist: $file\n";
 233         }
 234         return \@lines;
 235 }
 236
 237 exit;