:idseparator: -
+== Using generate_docs.pl
+
+This tool should perform all of the steps in "Doing it Manually", automatically. This tool requires some command line arguments and also requires some prerequisites.
+
+=== Installing Node
+
+Be sure and have Node installed.
+
+see https://github.com/nvm-sh/nvm#installation-and-update[Installing Node]
+
+[source,bash]
+----
+wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
+----
+
+=== Antora pre-reqs
+
+Once Node is installed, follow the Antora prereqs
+
+Summarized from https://docs.antora.org/antora/2.3/install/linux-requirements/[Antora pre-reqs]
+
+[source,bash]
+----
+$ nvm install --lts
+----
+
+=== Install Ansible
+
+There is one peice of the puzzle using Ansible at the moment. Better get that installed.
+
+[source,bash]
+----
+$ sudo apt-get install ansible
+----
+
+=== Run generate_docs.pl
+
+This tool does the rest of the work. You will be requried to supply these things:
+
+[cols=2*]
+|===
+
+|base-url
+|[eg: http//examplesite.org]
+
+|tmp-space
+|[Writable path where we stage antora UI repo and the antora HTML, eg: ../../tmp]
+
+|html-output
+|[Path where you want the generated HTML files to go, eg: /var/www/html]
+
+|antora-ui-repo
+|[git link to a repo, could be community repo: https://gitlab.com/antora/antora-ui-default.git]
+
+|antora-version
+|[target version of antora, eg: 2.1]
+
+|===
+
+Example:
+
+[source,bash]
+----
+$ cd Evergreen/docs-antora
+$ ./generate_docs.pl \
+--base-url http//examplesite.org/prod \
+--tmp-space ../../tmp \
+--html-output /var/www/html/prod \
+--antora-ui-repo https://git.evergreen-ils.org/eg-antora.git \
+--antora-version 2.3
+
+----
+
+NOTE: This tool will create two folders within the temp space folder path: "staging" and "antora-ui". These folders will be erased and re-created with each execution.
+
+
+
+== Doing it all manually
+
[source,bash]
----
$ git clone git://git.evergreen-ils.org/working/Evergreen.git
--- /dev/null
+#!/usr/bin/perl
+# ---------------------------------------------------------------
+# Copyright © 2020 MOBIUS
+# Blake Graham-Henderson <blake@mobiusconsortium.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+# ---------------------------------------------------------------
+
+
+use Getopt::Long;
+use Cwd;
+use File::Path;
+use Data::Dumper;
+
+my $base_url;
+my $tmp_space;
+my $html_output;
+my $antoraui_git;
+my $antora_version;
+my $help;
+
+
+
+GetOptions (
+"base-url=s" => \$base_url,
+"tmp-space=s" => \$tmp_space,
+"html-output=s" => \$html_output,
+"antora-ui-repo=s" => \$antoraui_git,
+"antora-version=s" => \$antora_version,
+"help" => \$help
+);
+
+sub help
+{
+ print <<HELP;
+ $0
+ --base-url http://example.com
+ --tmp-space ../../tmp
+ --html-output /var/www/html
+ --antora-ui-repo https://gitlab.com/antora/antora-ui-default.git
+ --antora-version 2.1
+
+ You must specify
+ --base-url [eg: http//examplesite.org]
+ --tmp-space [Writable path where we stage antora UI repo and the antora HTML, eg: ../../tmp]
+ --html-output [Path where you want the generated HTML files to go, eg: /var/www/html]
+ --antora-ui-repo [git link to a repo, could be community repo: https://gitlab.com/antora/antora-ui-default.git]
+ --antora-version [target version of antora, eg: 2.1]
+
+HELP
+ exit;
+}
+
+# Make sure the user supplied ALL of the options
+help() if(!$base_url || !$tmp_space || !$html_output || !$antoraui_git || !$antora_version);
+
+# make sure the URL is "right"
+$base_url = lc ($base_url);
+$base_url =~ s/^[\s\t]*//g;
+$base_url =~ s/[\s\t]*$//g;
+if ( !($base_url =~ m/^https?:\/\/.+\..+$/))
+{
+ print "Please specify a proper URL starting with http(s)\n";
+ exit;
+}
+
+# make sure the temp folder is good
+mkdir $tmp_space if ( !( -d $tmp_space ));
+
+# make sure the output folder is good
+mkdir $html_output if ( !( -d $html_output ));
+
+# deal with destination folders
+print "cleaning $tmp_space/antora-ui/\n" if (-d "$tmp_space/antora-ui");
+rmtree("$tmp_space/antora-ui/") if (-d "$tmp_space/antora-ui");
+
+print "cleaning $tmp_space/staging/\n" if (-d "$tmp_space/staging");
+rmtree("$tmp_space/staging/") if (-d "$tmp_space/staging");
+
+mkdir "$tmp_space/staging/";
+
+# Deal with ui repo
+exec_system_cmd("git clone $antoraui_git $tmp_space/antora-ui");
+
+exec_system_cmd("cd $tmp_space/antora-ui && npm install");
+
+exec_system_cmd("cd $tmp_space/antora-ui && gulp build && gulp pack");
+
+# Deal with root URL Antora configuration
+rewrite_yml($base_url,"site/url","site.yml");
+rewrite_yml("$tmp_space/staging","output/dir","site.yml");
+rewrite_yml("$tmp_space/antora-ui/build/ui-bundle.zip","ui/bundle/url","site.yml");
+
+
+#npm build antora
+exec_system_cmd('npm i @antora/cli@'.$antora_version.' @antora/site-generator-default@'.$antora_version);
+
+#make sure the lunr bits are accounted for
+exec_system_cmd('ansible-playbook setup_lunr.yml');
+exec_system_cmd('npm i antora-lunr');
+
+# Install the antora site generator with lunr
+exec_system_cmd('npm i -g antora-site-generator-lunr');
+
+# Now, finally, let's build antora
+exec_system_cmd('DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm -g root)" antora --generator antora-site-generator-lunr site.yml');
+
+# rsync to production
+exec_system_cmd('rsync -av --delete '.$tmp_space.'/staging/* '.$html_output.'/');
+
+print "Success: your site should be vieaable here: $base_url\n";
+
+sub rewrite_yml
+{
+ my $replacement = shift;
+ my $yml_path = shift;
+ my $file = shift;
+ my $contents = replace_yml($replacement,$yml_path,$file);
+ $contents =~ s/[\n\t]*$//g;
+ write_file("site.yml", $contents) if ($contents =~ m/$replacement/);
+}
+
+sub write_file
+{
+ my $file = shift;
+ my $contents = shift;
+
+ my $ret=1;
+ open(OUTPUT, '> '.$file) or $ret=0;
+ binmode(OUTPUT, ":utf8");
+ print OUTPUT "$contents\n";
+ close(OUTPUT);
+ return $ret;
+}
+
+sub replace_yml
+{
+ my $replacement = shift;
+ my $yml_path = shift;
+ my $file = shift;
+ my @path = split(/\//,$yml_path);
+ my @lines = @{read_file($file)};
+ my $depth = 0;
+ my $ret = '';
+ while(@lines[0])
+ {
+ my $line = shift @lines;
+ if(@path[0])
+ {
+ my $preceed_space = $depth * 2;
+ my $exp = '\s{'.$preceed_space.'}';
+ $exp = '[^\s#]' if $preceed_space == 0;
+ # print "testing $exp\n";
+ if($line =~ m/^$exp.*/)
+ {
+ if($line =~ m/^\s*@path[0].*/)
+ {
+ $depth++;
+ if(!@path[1])
+ {
+ # print "replacing '$line'\n";
+ my $t = @path[0];
+ $line =~ s/^(.*?$t[^\s]*).*$/\1 $replacement/g;
+ # print "now: '$line'\n";
+ }
+ shift @path;
+ }
+ }
+ }
+ $line =~ s/[\n\t]*$//g;
+ $ret .= "$line\n";
+ }
+
+ return $ret;
+}
+
+sub exec_system_cmd
+{
+ my $cmd = shift;
+ print "executing $cmd\n";
+ system($cmd) == 0
+ or die "system @args failed: $?";
+}
+
+sub read_file
+{
+ my $file = shift;
+ my $trys=0;
+ my $failed=0;
+ my @lines;
+ #print "Attempting open\n";
+ if(-e $file)
+ {
+ my $worked = open (inputfile, '< '. $file);
+ if(!$worked)
+ {
+ print "******************Failed to read file*************\n";
+ }
+ binmode(inputfile, ":utf8");
+ while (!(open (inputfile, '< '. $file)) && $trys<100)
+ {
+ print "Trying again attempt $trys\n";
+ $trys++;
+ sleep(1);
+ }
+ if($trys<100)
+ {
+ #print "Finally worked... now reading\n";
+ @lines = <inputfile>;
+ close(inputfile);
+ }
+ else
+ {
+ print "Attempted $trys times. COULD NOT READ FILE: $file\n";
+ }
+ close(inputfile);
+ }
+ else
+ {
+ print "File does not exist: $file\n";
+ }
+ return \@lines;
+}
+
+exit;
\ No newline at end of file
projects / evergreen-equinox.git / commitdiff