From 28f9de156f2b76facc2b32f7f2c2efc9e27b338a Mon Sep 17 00:00:00 2001 From: blake Date: Tue, 12 May 2020 17:32:35 -0500 Subject: [PATCH] LP#1848524: Add doc site generator generate_docs.pl Also update the README to document the new steps to create the Antora site. Signed-off-by: blake Signed-off-by: Galen Charlton --- docs-antora/README.adoc | 79 +++++++++++++++ docs-antora/generate_docs.pl | 233 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 312 insertions(+) create mode 100644 docs-antora/generate_docs.pl diff --git a/docs-antora/README.adoc b/docs-antora/README.adoc index 01cd101b2e..eac6cfb4c3 100644 --- a/docs-antora/README.adoc +++ b/docs-antora/README.adoc @@ -2,6 +2,85 @@ :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 diff --git a/docs-antora/generate_docs.pl b/docs-antora/generate_docs.pl new file mode 100644 index 0000000000..0ca827272e --- /dev/null +++ b/docs-antora/generate_docs.pl @@ -0,0 +1,233 @@ +#!/usr/bin/perl +# --------------------------------------------------------------- +# Copyright © 2020 MOBIUS +# Blake Graham-Henderson +# +# 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 < '.$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 = ; + 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 -- 2.11.0