From 6917eeb9da4f0c402c18bb50a4be21ec62f074b4 Mon Sep 17 00:00:00 2001 From: Jason Boyer Date: Thu, 10 Sep 2020 17:17:58 -0400 Subject: [PATCH] Antora Docs Supplement Update the Antora build procedure to no longer rely on ansible and automatically build the search-enabled version of the documentation. Signed-off-by: Jason Boyer Signed-off-by: Galen Charlton --- docs/.gitignore | 3 ++ docs/README.adoc | 74 +++++---------------------- docs/generate_docs.pl | 77 ++++++++++++++--------------- docs/setup_lunr.yml | 24 --------- docs/ui/.editorconfig | 9 ---- docs/ui/.eslintrc | 9 ---- docs/ui/.gitignore | 3 -- docs/ui/.gitlab-ci.yml | 55 --------------------- docs/ui/.gulp.json | 4 -- docs/ui/.nvmrc | 1 - docs/ui/.stylelintrc | 7 --- docs/ui/ui-lunr/partials/header-content.hbs | 35 +++++++++++++ docs/ui/ui-lunr/partials/toolbar.hbs | 8 +++ 13 files changed, 96 insertions(+), 213 deletions(-) delete mode 100644 docs/setup_lunr.yml delete mode 100644 docs/ui/.editorconfig delete mode 100644 docs/ui/.eslintrc delete mode 100644 docs/ui/.gitignore delete mode 100644 docs/ui/.gitlab-ci.yml delete mode 100644 docs/ui/.gulp.json delete mode 100644 docs/ui/.nvmrc delete mode 100644 docs/ui/.stylelintrc create mode 100644 docs/ui/ui-lunr/partials/header-content.hbs create mode 100644 docs/ui/ui-lunr/partials/toolbar.hbs diff --git a/docs/.gitignore b/docs/.gitignore index 504afef81f..ac4b26ee37 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,5 @@ node_modules/ package-lock.json +build +output +site-working.yml diff --git a/docs/README.adoc b/docs/README.adoc index 899d09eea1..b911f2303b 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -28,15 +28,6 @@ Summarized from https://docs.antora.org/antora/2.3/install/linux-requirements/[A $ 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: @@ -45,19 +36,19 @@ This tool does the rest of the work. You will be requried to supply these things |=== |base-url -|[eg: http//examplesite.org] +|[URL where html output is expected to be available eg: http//examplesite.org] |tmp-space -|[Writable path where we stage antora UI repo and the antora HTML, eg: ../../tmp] +|[Writable path for staging the antora UI repo and build files, defaults to ./build] |html-output -|[Path where you want the generated HTML files to go, eg: /var/www/html] +|[Path for the generated HTML files, defaults to ./output] |antora-ui-repo -|[git link to a repo, could be community repo: https://gitlab.com/antora/antora-ui-default.git] +|[Antora-UI repository for the built UI, defaults to git://git.evergreen-ils.org/eg-antora.git] |antora-version -|[target version of antora, eg: 2.1] +|[Version of antora to use for build, defaults to 2.3] |=== @@ -75,7 +66,7 @@ $ ./generate_docs.pl \ ---- -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. +NOTE: This tool will create the tmp-space and html-ouput directories if they do not exist. These folders will be erased and re-created with each execution. @@ -83,10 +74,9 @@ NOTE: This tool will create two folders within the temp space folder path: "stag [source,bash] ---- -$ git clone git://git.evergreen-ils.org/working/Evergreen.git +$ git clone git://git.evergreen-ils.org/Evergreen.git $ git clone git://git.evergreen-ils.org/eg-antora.git $ cd Evergreen -$ git checkout collab/blake/LP1848524_antora_ize_docs ---- First we have to install antora: @@ -96,14 +86,16 @@ https://docs.antora.org/antora/2.1/install/install-antora/ [source,bash] ---- $ cd docs -# (we want to install into directory as opposed to globally) -$ npm i @antora/cli@2.1 @antora/site-generator-default@2.1 +# (we want to install into the local directory as opposed to globally) +$ npm install @antora/cli@2.3 @antora/site-generator-default@2.3 antora-lunr antora-site-generator-lunr ---- Now, install the ui pre-reqs building -lifted from: +lifted from https://docs.antora.org/antora-ui-default/set-up-project/ +and +https://github.com/Mogztter/antora-lunr [source,bash] ---- @@ -133,7 +125,7 @@ Build: [source,bash] ---- $ cd ../Evergreen/docs -antora site.yml +DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora --generator antora-site-generator-lunr site.yml ---- If all went well - then you will have the site built in the output folder that was configured in site.yml! @@ -146,43 +138,3 @@ NOTE: https://blog.anoff.io/2019-02-15-antora-first-steps/ NOTE: https://owncloud.org/news/owncloud-docs-migrating-antora-pt-1-2/ - -== Search stuff - -First you need to have ansible installed - -NOTE: If you want to manually edit the file, you don't need to install ansible - -[source,bash] ----- -$ sudo apt-get -y install ansible ----- - -Now, let's run through the antora-lunr procedure: - -NOTE: Lifted from the base install notes from the https://github.com/Mogztter/antora-lunr[ git repo] - - -[source,bash] ----- -$ ansible-playbook setup_lunr.yml - ----- - -This should have edited this file: node_modules/@antora/site-generator-default/lib/generate-site.js -as outlined in the git repo notes - -Now, install the lunr bits (from the docs folder) - -[source,bash] ----- -$ npm i antora-lunr ----- - -And now, you can re-generate the site but this time with the search box: - -[source,bash] ----- -$ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora site.yml ----- - diff --git a/docs/generate_docs.pl b/docs/generate_docs.pl index e255141b59..c817b5d80c 100755 --- a/docs/generate_docs.pl +++ b/docs/generate_docs.pl @@ -21,10 +21,10 @@ use File::Path; use Data::Dumper; my $base_url; -my $tmp_space; -my $html_output; -my $antoraui_git; -my $antora_version; +my $tmp_space = './build'; +my $html_output = './output'; +my $antoraui_git = 'https://gitlab.com/antora/antora-ui-default.git'; +my $antora_version = '2.3'; my $help; @@ -46,14 +46,14 @@ sub help --tmp-space ../../tmp --html-output /var/www/html --antora-ui-repo https://gitlab.com/antora/antora-ui-default.git - --antora-version 2.1 + --antora-version 2.3 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] + --base-url [URL where html output is expected to be available eg: http//examplesite.org/docs] + --tmp-space [Writable path for staging the antora UI repo and build files, defaults to ./build] + --html-output [Path for the generated HTML files, defaults to ./output] + --antora-ui-repo [Antora-UI repository for the built UI, defaults to https://gitlab.com/antora/antora-ui-default.git] + --antora-version [Target version of antora, defaults to 2.3] HELP exit; @@ -72,20 +72,25 @@ if ( !($base_url =~ m/^https?:\/\/.+\..+$/)) 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"); +if (-d "$tmp_space/antora-ui") { + print "cleaning $tmp_space/antora-ui/\n"; + rmtree("$tmp_space/antora-ui/"); +} -print "cleaning $tmp_space/staging/\n" if (-d "$tmp_space/staging"); -rmtree("$tmp_space/staging/") if (-d "$tmp_space/staging"); +if (-d "$html_output") { + print "cleaning $html_output/\n"; + rmtree("$html_output/"); +} -mkdir "$tmp_space/staging/"; +# make sure the temp folder is good +mkdir $tmp_space unless ( -d $tmp_space ); + +# make sure the output folder is good +mkdir $html_output unless ( -d $html_output ); + +die "Both " . $tmp_space . " and " . $html_output . " must be writable!" unless ( -w $tmp_space && -w $html_output ); # Deal with ui repo exec_system_cmd("git clone $antoraui_git $tmp_space/antora-ui"); @@ -94,31 +99,23 @@ exec_system_cmd("cd $tmp_space/antora-ui && npm install gulp-cli"); exec_system_cmd("cd $tmp_space/antora-ui && npm install"); -exec_system_cmd("cd $tmp_space/antora-ui && $tmp_space/antora-ui/node_modules/.bin/gulp build && $tmp_space/antora-ui/node_modules/.bin/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"); - +exec_system_cmd("cd $tmp_space/antora-ui && ./node_modules/.bin/gulp build && ./node_modules/.bin/gulp pack"); -#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'); +exec_system_cmd("cp site.yml site-working.yml"); -# Install the antora site generator with lunr -exec_system_cmd('npm i antora-site-generator-lunr'); +# Deal with root URL Antora configuration +rewrite_yml($base_url,"site/url","site-working.yml"); +rewrite_yml("$html_output","output/dir","site-working.yml"); +rewrite_yml("$tmp_space/antora-ui/build/ui-bundle.zip","ui/bundle/url","site-working.yml"); -# Now, finally, let's build antora -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.yml'); +#npm install antora +exec_system_cmd('npm install @antora/cli@' . $antora_version . ' @antora/site-generator-default@' . $antora_version . ' antora-lunr antora-site-generator-lunr'); -# rsync to production -exec_system_cmd('rsync -av --delete '.$tmp_space.'/staging/* '.$html_output.'/'); +# Now, finally, let's build the site +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'); -print "Success: your site should be viewable here: $base_url\n"; +print "Success: your site files are available at " . $html_output . " and can be moved into place for access at " . $base_url . "\n"; sub rewrite_yml { @@ -127,7 +124,7 @@ sub rewrite_yml 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/); + write_file($file, $contents) if ($contents =~ m/$replacement/); } sub write_file diff --git a/docs/setup_lunr.yml b/docs/setup_lunr.yml deleted file mode 100644 index 583fe3678d..0000000000 --- a/docs/setup_lunr.yml +++ /dev/null @@ -1,24 +0,0 @@ ---- -- hosts: 'localhost' - connection: local - remote_user: user - become_method: sudo - tasks: - - name: Insert const generateIndex - lineinfile: - path: node_modules/@antora/site-generator-default/lib/generate-site.js - insertafter: 'use strict' - line: "const generateIndex = require('antora-lunr')" - - - name: Insert const index - lineinfile: - path: node_modules/@antora/site-generator-default/lib/generate-site.js - insertafter: 'const siteFiles = mapSit' - line: " const index = generateIndex(playbook, pages)" - - - name: Insert line siteFiles.push(generateIndex.createIndexFile(index)) - lineinfile: - path: node_modules/@antora/site-generator-default/lib/generate-site.js - insertafter: 'const index = generateIn' - line: " siteFiles.push(generateIndex.createIndexFile(index))" -... \ No newline at end of file diff --git a/docs/ui/.editorconfig b/docs/ui/.editorconfig deleted file mode 100644 index c6c8b36219..0000000000 --- a/docs/ui/.editorconfig +++ /dev/null @@ -1,9 +0,0 @@ -root = true - -[*] -indent_style = space -indent_size = 2 -end_of_line = lf -charset = utf-8 -trim_trailing_whitespace = true -insert_final_newline = true diff --git a/docs/ui/.eslintrc b/docs/ui/.eslintrc deleted file mode 100644 index f8fb261492..0000000000 --- a/docs/ui/.eslintrc +++ /dev/null @@ -1,9 +0,0 @@ -{ - "extends": "standard", - "rules": { - "arrow-parens": ["error", "always"], - "comma-dangle": ["error", "always-multiline"], - "max-len": [1, 120, 2], - "spaced-comment": "off" - } -} diff --git a/docs/ui/.gitignore b/docs/ui/.gitignore deleted file mode 100644 index 57834a1291..0000000000 --- a/docs/ui/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -/build/ -/node_modules/ -/public/ diff --git a/docs/ui/.gitlab-ci.yml b/docs/ui/.gitlab-ci.yml deleted file mode 100644 index b183e33c59..0000000000 --- a/docs/ui/.gitlab-ci.yml +++ /dev/null @@ -1,55 +0,0 @@ -image: node:10.14.2-stretch -stages: [setup, verify, deploy] -install: - stage: setup - cache: - paths: - - .cache/npm - script: - - &npm_install - npm install --quiet --no-progress --cache=.cache/npm -lint: - stage: verify - cache: &pull_cache - policy: pull - paths: - - .cache/npm - script: - - *npm_install - - node_modules/.bin/gulp lint -bundle-stable: - stage: deploy - only: - - master@antora/antora-ui-default - cache: *pull_cache - script: - - *npm_install - - node_modules/.bin/gulp bundle - artifacts: - paths: - - build/ui-bundle.zip -bundle-dev: - stage: deploy - except: - - master - cache: *pull_cache - script: - - *npm_install - - node_modules/.bin/gulp bundle - artifacts: - expire_in: 1 day # unless marked as keep from job page - paths: - - build/ui-bundle.zip -pages: - stage: deploy - only: - - master@antora/antora-ui-default - cache: *pull_cache - script: - - *npm_install - - node_modules/.bin/gulp preview:build - # FIXME figure out a way to avoid copying these files to preview site - - rm -rf public/_/{helpers,layouts,partials} - artifacts: - paths: - - public diff --git a/docs/ui/.gulp.json b/docs/ui/.gulp.json deleted file mode 100644 index 2da9b16c1e..0000000000 --- a/docs/ui/.gulp.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "description": "Build tasks for the Antora default UI project", - "flags.tasksDepth": 1 -} diff --git a/docs/ui/.nvmrc b/docs/ui/.nvmrc deleted file mode 100644 index f599e28b8a..0000000000 --- a/docs/ui/.nvmrc +++ /dev/null @@ -1 +0,0 @@ -10 diff --git a/docs/ui/.stylelintrc b/docs/ui/.stylelintrc deleted file mode 100644 index 344318f3c5..0000000000 --- a/docs/ui/.stylelintrc +++ /dev/null @@ -1,7 +0,0 @@ -{ - "extends": "stylelint-config-standard", - "rules": { - "comment-empty-line-before": null, - "no-descending-specificity": null, - } -} diff --git a/docs/ui/ui-lunr/partials/header-content.hbs b/docs/ui/ui-lunr/partials/header-content.hbs new file mode 100644 index 0000000000..bdc6271443 --- /dev/null +++ b/docs/ui/ui-lunr/partials/header-content.hbs @@ -0,0 +1,35 @@ + diff --git a/docs/ui/ui-lunr/partials/toolbar.hbs b/docs/ui/ui-lunr/partials/toolbar.hbs new file mode 100644 index 0000000000..4140e2342e --- /dev/null +++ b/docs/ui/ui-lunr/partials/toolbar.hbs @@ -0,0 +1,8 @@ + -- 2.11.0