docs/README.adoc

   1 = Antora Docs build procedure
   2
   3 :idseparator: -
   4
   5 == Using generate_docs.pl
   6
   7 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.
   8
   9 === Installing Node
  10
  11 Be sure and have Node installed.
  12
  13 see https://github.com/nvm-sh/nvm#installation-and-update[Installing Node]
  14
  15 [source,bash]
  16 ----
  17 wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
  18 ----
  19
  20 === Antora pre-reqs
  21
  22 Once Node is installed, follow the Antora prereqs
  23
  24 Summarized from https://docs.antora.org/antora/2.3/install/linux-requirements/[Antora pre-reqs]
  25
  26 [source,bash]
  27 ----
  28 $ nvm install --lts
  29 ----
  30
  31 === Install Ansible
  32
  33 There is one peice of the puzzle using Ansible at the moment. Better get that installed.
  34
  35 [source,bash]
  36 ----
  37 $ sudo apt-get install ansible
  38 ----
  39
  40 === Run generate_docs.pl
  41
  42 This tool does the rest of the work. You will be requried to supply these things:
  43
  44 [cols=2*]
  45 |===
  46
  47 |base-url
  48 |[eg: http//examplesite.org]
  49
  50 |tmp-space
  51 |[Writable path where we stage antora UI repo and the antora HTML, eg: ../../tmp]
  52
  53 |html-output
  54 |[Path where you want the generated HTML files to go, eg: /var/www/html]
  55
  56 |antora-ui-repo
  57 |[git link to a repo, could be community repo: https://gitlab.com/antora/antora-ui-default.git]
  58
  59 |antora-version
  60 |[target version of antora, eg: 2.1]
  61
  62 |===
  63
  64 Example:
  65
  66 [source,bash]
  67 ----
  68 $ cd Evergreen/docs-antora
  69 $ ./generate_docs.pl \
  70 --base-url http//examplesite.org/prod \
  71 --tmp-space ../../tmp \
  72 --html-output /var/www/html/prod \
  73 --antora-ui-repo https://git.evergreen-ils.org/eg-antora.git \
  74 --antora-version 2.3
  75
  76 ----
  77
  78 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.
  79
  80
  81
  82 == Doing it all manually
  83
  84 [source,bash]
  85 ----
  86 $ git clone git://git.evergreen-ils.org/working/Evergreen.git
  87 $ git clone git://git.evergreen-ils.org/eg-antora.git
  88 $ cd Evergreen
  89 $ git checkout collab/blake/LP1848524_antora_ize_docs
  90 ----
  91
  92 First we have to install antora:
  93 Summarized from
  94 https://docs.antora.org/antora/2.1/install/install-antora/
  95
  96 [source,bash]
  97 ----
  98 $ cd docs-antora
  99 # (we want to install into directory as opposed to globally)
 100 $ npm i @antora/cli@2.1 @antora/site-generator-default@2.1
 101 ----
 102
 103
 104 Now, install the ui pre-reqs building
 105 lifted from:
 106 https://docs.antora.org/antora-ui-default/set-up-project/
 107
 108 [source,bash]
 109 ----
 110 $ cd ../../eg-antora
 111 $ npm install
 112 $ npm gulp-bundle
 113 ----
 114
 115 At this point you should find a file in:
 116
 117 NOTE: build/ui-bundle.zip
 118
 119 Now you can build the website. But you may want to edit the file:
 120
 121 NOTE: docs-antora/site.yml
 122
 123 Because the output folder for the website is defaulted to
 124
 125 NOTE: /var/www/html/prod
 126
 127 And the default web URL is:
 128
 129 NOTE: http://localhost/prod
 130
 131 Build:
 132
 133 [source,bash]
 134 ----
 135 $ cd ../Evergreen/docs-antora
 136 antora site.yml
 137 ----
 138
 139 If all went well - then you will have the site built in the output folder that was configured in site.yml!
 140
 141 Interesting reading related to Antora and AsciiDoc and AsciiDoctor
 142
 143 NOTE: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
 144
 145 NOTE: https://blog.anoff.io/2019-02-15-antora-first-steps/
 146
 147 NOTE: https://owncloud.org/news/owncloud-docs-migrating-antora-pt-1-2/
 148
 149
 150 == Search stuff
 151
 152 First you need to have ansible installed
 153
 154 NOTE: If you want to manually edit the file, you don't need to install ansible
 155
 156 [source,bash]
 157 ----
 158 $ sudo apt-get -y install ansible
 159 ----
 160
 161 Now, let's run through the antora-lunr procedure:
 162
 163 NOTE: Lifted from the base install notes from the  https://github.com/Mogztter/antora-lunr[ git repo]
 164
 165
 166 [source,bash]
 167 ----
 168 $ ansible-playbook setup_lunr.yml
 169
 170 ----
 171
 172 This should have edited this file: node_modules/@antora/site-generator-default/lib/generate-site.js
 173 as outlined in the git repo notes
 174
 175 Now, install the lunr bits (from docs-antora folder)
 176
 177 [source,bash]
 178 ----
 179 $ npm i antora-lunr
 180 ----
 181
 182 And now, you can re-generate the site but this time with the search box:
 183
 184 [source,bash]
 185 ----
 186 $ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora site.yml
 187 ----
 188