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 # To run this script on Windows:
  18 # 1. Install Strawberry Perl from https://strawberryperl.com/
  19 # 2. Install Node from https://nodejs.org
  20 # 3. Open a new cmd window
  21 # 4. Clone the Evergreen git repository if you don't have it already.  Instructions
  22 #    can be found at https://wiki.evergreen-ils.org/doku.php?id=newdevs:git:install
  23 # 5. In your cmd window, `cd` into the Evergreen docs directory.  For example, if
  24 #    your local copy of the Evergreen repo is at C:\Users\me\projects\Evergreen, type
  25 #    `cd \Users\me\projects\Evergreen\docs` (without the backticks) into the cmd window.
  26 # 6. In your cmd window, type: perl generate_docs.pl --base-url http://example.com
  27 # 7. In a browser, open the docs/output/index.html file.  For examle, if your local
  28 #    copy of the Evergreen repo is at C:\Users\me\projects\Evergreen, type
  29 #    file:///C:/Users/me/projects/Evergreen/docs/output/index.html
  30 #    into your browser's URL bar.
  31 # 8. If you click on the "Evergreen Documentation" phrase at the top, you will get an
  32 #    error because it will link you to "example.com". Don't click on that :)
  33
  34 use Getopt::Long;
  35 use Cwd;
  36 use File::Path;
  37 use Data::Dumper;
  38 use File::Copy;
  39
  40 my $base_url;
  41 my $tmp_space = './build';
  42 my $html_output = './output';
  43 my $antoraui_git = 'git://git.evergreen-ils.org/eg-antora.git';
  44 my $antoraui_git_branch = 'main';
  45 my $antora_version = '3.1.7';
  46 my $help;
  47
  48
  49
  50 GetOptions (
  51 "base-url=s" => \$base_url,
  52 "tmp-space=s" => \$tmp_space,
  53 "html-output=s" => \$html_output,
  54 "antora-ui-repo=s" => \$antoraui_git,
  55 "antora-ui-repo-branch=s" => \$antoraui_git_branch,
  56 "antora-version=s" => \$antora_version,
  57 "help" => \$help
  58 );
  59
  60 sub help
  61 {
  62     print <<HELP;
  63     $0
  64     --base-url http://example.com
  65     --tmp-space ../../tmp
  66     --html-output /var/www/html
  67     --antora-ui-repo git://git.evergreen-ils.org/eg-antora.git
  68     --antora-version 3.1.7
  69
  70     You must specify
  71     --base-url                                    [URL where html output is expected to be available eg: http//examplesite.org/docs]
  72     --tmp-space                                   [Writable path for staging the antora UI repo and build files, defaults to ./build]
  73     --html-output                                 [Path for the generated HTML files, defaults to ./output]
  74     --antora-ui-repo                              [Antora-UI repository for the built UI, defaults to git://git.evergreen-ils.org/eg-antora.git]
  75     --antora-ui-repo-branch                       [OPTIONAL: Antora-UI repository checkout branch, Defaults to "main"]
  76     --antora-version                              [Target version of antora, defaults to 3.1.7]
  77
  78 HELP
  79     exit;
  80 }
  81
  82 # Make sure the user supplied ALL of the options
  83 help() if(!$base_url || !$tmp_space || !$html_output || !$antoraui_git || !$antora_version);
  84
  85 # make sure the URL is "right"
  86 $base_url = lc ($base_url);
  87 $base_url =~ s/^[\s\t]*//g;
  88 $base_url =~ s/[\s\t]*$//g;
  89 if ( !($base_url =~ m/^https?:\/\/.+\..+$/))
  90 {
  91     print "Please specify a proper URL starting with http(s)\n";
  92     exit;
  93 }
  94
  95
  96 # deal with destination folders
  97 if (-d "$tmp_space/antora-ui") {
  98     print "cleaning $tmp_space/antora-ui/\n";
  99     rmtree("$tmp_space/antora-ui/");
 100 }
 101
 102 if (-d "$html_output") {
 103     print "cleaning $html_output/\n";
 104     rmtree("$html_output/");
 105 }
 106
 107 # make sure the temp folder is good
 108 mkdir $tmp_space unless ( -d $tmp_space );
 109
 110 # make sure the output folder is good
 111 mkdir $html_output unless ( -d $html_output );
 112
 113 die "Both " . $tmp_space . " and " . $html_output . " must be writable!" unless ( -w $tmp_space && -w $html_output );
 114
 115 # Deal with ui repo
 116 exec_system_cmd("git clone $antoraui_git $tmp_space/antora-ui");
 117
 118 exec_system_cmd("cd $tmp_space/antora-ui && git checkout $antoraui_git_branch");
 119
 120 exec_system_cmd("cd $tmp_space/antora-ui && npm install gulp-cli");
 121
 122 exec_system_cmd("cd $tmp_space/antora-ui && npm install");
 123
 124 exec_system_cmd("cd $tmp_space/antora-ui && npx gulp build && npx gulp pack");
 125
 126
 127 copy('site.yml', 'site-working.yml');
 128
 129 # Deal with root URL Antora configuration
 130 rewrite_yml($base_url,"site/url","site-working.yml");
 131 rewrite_yml("$html_output","output/dir","site-working.yml");
 132 rewrite_yml("$tmp_space/antora-ui/build/ui-bundle.zip","ui/bundle/url","site-working.yml");
 133
 134 # clean up before installing Antora - it was observed during the
 135 # upgrade from 2.3 to 3.1.7 that a package.json node_modules
 136 # from 2.3 could cause the older version of the CLI to be
 137 # used instead of the new one
 138 if (-d 'node_modules') {
 139     rmtree('node_modules');
 140 }
 141 unlink('package.json');
 142 unlink('package-lock.json');
 143
 144 #npm install antora
 145 exec_system_cmd('npm install antora@' . $antora_version . ' @antora/lunr-extension@^1.0.0-alpha.8');
 146
 147 # Now, finally, let's build the site
 148 local $ENV{NODE_PATH} = `npm root`;
 149 exec_system_cmd('npx antora site-working.yml');
 150
 151 print "Success: your site files are available at " . $html_output . " and can be moved into place for access at " . $base_url . "\n";
 152
 153 sub rewrite_yml
 154 {
 155     my $replacement = shift;
 156     my $yml_path = shift;
 157     my $file = shift;
 158     my $contents = replace_yml($replacement,$yml_path,$file);
 159     $contents =~ s/[\n\t]*$//g;
 160     write_file($file, $contents) if ($contents =~ m/$replacement/);
 161 }
 162
 163 sub write_file
 164 {
 165     my $file = shift;
 166     my $contents = shift;
 167
 168         my $ret=1;
 169         open(OUTPUT, '> '.$file) or $ret=0;
 170         binmode(OUTPUT, ":utf8");
 171         print OUTPUT "$contents\n";
 172         close(OUTPUT);
 173         return $ret;
 174 }
 175
 176 sub replace_yml
 177 {
 178     my $replacement = shift;
 179     my $yml_path = shift;
 180     my $file = shift;
 181     my @path = split(/\//,$yml_path);
 182     my @lines = @{read_file($file)};
 183     my $depth = 0;
 184     my $ret = '';
 185     while(@lines[0])
 186     {
 187         my $line = shift @lines;
 188         if(@path[0])
 189         {
 190             my $preceed_space = $depth * 2;
 191             my $exp = '\s{'.$preceed_space.'}';
 192             $exp = '[^\s#]' if $preceed_space == 0;
 193             # print "testing $exp\n";
 194             if($line =~ m/^$exp.*/)
 195             {
 196                 if($line =~ m/^\s*@path[0].*/)
 197                 {
 198                     $depth++;
 199                     if(!@path[1])
 200                     {
 201                         # print "replacing '$line'\n";
 202                         my $t = @path[0];
 203                         $line =~ s/^(.*?$t[^\s]*).*$/\1 $replacement/g;
 204                         # print "now: '$line'\n";
 205                     }
 206                     shift @path;
 207                 }
 208             }
 209         }
 210         $line =~ s/[\n\t]*$//g;
 211         $ret .= "$line\n";
 212     }
 213
 214     return $ret;
 215 }
 216
 217 sub exec_system_cmd
 218 {
 219     my $cmd = shift;
 220     print "executing $cmd\n";
 221     system($cmd) == 0
 222         or die "system @args failed: $?";
 223 }
 224
 225 sub read_file
 226 {
 227         my $file = shift;
 228         my $trys=0;
 229         my $failed=0;
 230         my @lines;
 231         #print "Attempting open\n";
 232         if(-e $file)
 233         {
 234                 my $worked = open (inputfile, '< '. $file);
 235                 if(!$worked)
 236                 {
 237                         print "******************Failed to read file*************\n";
 238                 }
 239         binmode(inputfile, ":utf8");
 240                 while (!(open (inputfile, '< '. $file)) && $trys<100)
 241                 {
 242                         print "Trying again attempt $trys\n";
 243                         $trys++;
 244                         sleep(1);
 245                 }
 246                 if($trys<100)
 247                 {
 248                         #print "Finally worked... now reading\n";
 249                         @lines = <inputfile>;
 250                         close(inputfile);
 251                 }
 252                 else
 253                 {
 254                         print "Attempted $trys times. COULD NOT READ FILE: $file\n";
 255                 }
 256                 close(inputfile);
 257         }
 258         else
 259         {
 260                 print "File does not exist: $file\n";
 261         }
 262         return \@lines;
 263 }
 264
 265 exit;