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