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 === Run generate_docs.pl
  32
  33 This tool does the rest of the work. You will be requried to supply these things:
  34
  35 [cols="2*"]
  36 |===
  37
  38 |base-url
  39 |[URL where html output is expected to be available eg: http//examplesite.org]
  40
  41 |tmp-space
  42 |[Writable path for staging the antora UI repo and build files, defaults to ./build]
  43
  44 |html-output
  45 |[Path for the generated HTML files, defaults to ./output]
  46
  47 |antora-ui-repo
  48 |[Antora-UI repository for the built UI, defaults to git://git.evergreen-ils.org/eg-antora.git]
  49
  50 |antora-version
  51 |[Version of antora to use for build, defaults to 2.3]
  52
  53 |===
  54
  55 Example:
  56
  57 [source,bash]
  58 ----
  59 $ cd Evergreen/docs
  60 $ ./generate_docs.pl \
  61 --base-url http//examplesite.org/prod \
  62 --tmp-space ../../tmp \
  63 --html-output /var/www/html/prod \
  64 --antora-ui-repo git://git.evergreen-ils.org/eg-antora.git \
  65 --antora-version 2.3
  66
  67 ----
  68
  69 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.
  70
  71
  72
  73 == Doing it all manually
  74
  75 [source,bash]
  76 ----
  77 $ git clone git://git.evergreen-ils.org/Evergreen.git
  78 $ git clone git://git.evergreen-ils.org/eg-antora.git
  79 $ cd Evergreen
  80 ----
  81
  82 First we have to install antora:
  83 Summarized from
  84 https://docs.antora.org/antora/2.1/install/install-antora/
  85
  86 [source,bash]
  87 ----
  88 $ cd docs
  89 # (we want to install into the local directory as opposed to globally)
  90 $ npm install @antora/cli@2.3 @antora/site-generator-default@2.3 antora-lunr antora-site-generator-lunr
  91 ----
  92
  93
  94 Now, install the ui pre-reqs building
  95 lifted from
  96 https://docs.antora.org/antora-ui-default/set-up-project/
  97 and
  98 https://github.com/Mogztter/antora-lunr
  99
 100 [source,bash]
 101 ----
 102 $ cd ../../eg-antora
 103 $ npm install
 104 $ npm gulp-bundle
 105 ----
 106
 107 At this point you should find a file in:
 108
 109 NOTE: build/ui-bundle.zip
 110
 111 Note that if you are using a customized build of antora-ui you will need to include the proper lunr ui components in your local repository. Now you can build the website but you may want to edit the file:
 112
 113 NOTE: docs/site.yml
 114
 115 Because the output folder for the website is defaulted to
 116
 117 NOTE: /var/www/html/prod
 118
 119 And the default web URL is:
 120
 121 NOTE: http://localhost/prod
 122
 123 Build:
 124
 125 [source,bash]
 126 ----
 127 $ cd ../Evergreen/docs
 128 DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora --generator antora-site-generator-lunr site.yml
 129 ----
 130
 131 If all went well - then you will have the site built in the output folder that was configured in site.yml!
 132
 133 Interesting reading related to Antora and AsciiDoc and AsciiDoctor
 134
 135 NOTE: https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
 136
 137 NOTE: https://blog.anoff.io/2019-02-15-antora-first-steps/
 138
 139 NOTE: https://owncloud.org/news/owncloud-docs-migrating-antora-pt-1-2/
 140