f57d03bf67acb06c60f5a0219d82f9cff98f29ce
[Evergreen.git] / 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