README.adoc 9.39 KB
Newer Older
1
= New Bonita Documentation Site
2
3
4
5
6
7
8
9
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
10
11
// External URIs:
:url-antora: https://antora.org
12
:url-antora-docs: https://docs.antora.org/antora/3.0
13
:url-asciidoc: https://docs.asciidoctor.org/asciidoc/latest/
14
15
16
17
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation

18
image::https://api.netlify.com/api/v1/badges/df65c069-bb52-46d2-8bf0-8e16b6b21482/deploy-status[alt=Netlify Status,link=https://app.netlify.com/sites/documentation-bonita/deploys]
19
image::https://github.com/bonitasoft/bonita-documentation-site/actions/workflows/propagate-doc-upwards.yml/badge.svg[alt=Propagate documentation,link=https://github.com/bonitasoft/bonita-documentation-site/actions/workflows/propagate-doc-upwards.yml/badge.svg]
20

21
This repository lets you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoc}:[AsciiDoc]
22
documentation content stored in various Git repositories.
23
24


25
26
== Documentation

27
See the xref:docs/README.adoc[dedicated folder] for
28
29
30
31
32

* documentation content contribution tips/guidelines
* architecture
* maintainers guides
* and much more
33

34
35
More details are available in the xref:docs/architecture.adoc[Architecture Documentation].

36
37
38
39
40
41

== Build

=== Requirements


42
{url-node}[Node 16.x] (may work with newer versions, no guarantee).
43
44

While you can install Node from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to install and manage Node.
45
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine. Then run `nvm use`.
46

47
48
49
50
51
[NOTE]
====
* all commands are intended to be run from the repository root folder.
* the generated documentation is available in the `build/site` folder.
====
52

53
Don't forget to run `npm install` the first time you build the project or on `package.json` changes.
54

55
Check that the `Antora` CLI is available by calling `./node_modules/.bin/antora --version`.
56
57


58
59
[#non-production-build]
== Non production build
60

61
62
[[preview]]
=== Preview support
63

64
65
The easiest way is to use a script that generates the documentation partially and/or with specific settings for both local
developments, Pull Request previews or to produce documentation archives.
66

67
This includes building the documentation using:
68

69
70
71
* already checkout local documentation content repositories
* single branch for all components
* single branch of a single component
72
* a set of branches of various components. It lets validate {url-antora-docs}/page/page-links/[references between pages that belong to different docs components and/or versions]
73
* ....
74

75
76
77
78
79
To know all available options, run
[source,shell script]
----
./build-preview.bash --help
----
80

81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
[NOTE]
=====
An additional `build-preview-dev.bash` script is available: it calls `build-preview.bash` with convenient defaults for
local build. +
In the following, we use both scripts indifferently.
=====

[source,shell script]
.Build a single component version using locally modified document content sources (see <<local-content, required setup>>)
----
./build-preview-dev.bash --local-sources \
  --component bonita \
  --branch fix/a_major_documentation_content_fix
----

[source,shell script]
.Build BCD 3.4, Bonita 7.11 and Bonita 2021.1 versions (cross reference component versions check)
----
./build-preview-dev.bash \
  --use-multi-repositories \
  --component-with-branches bcd:3.4 \
  --component-with-branches bonita:7.11,2021.1
----

==== Preview support overview

The documentation is built by passing a playbook file to the Antora CLI. For more details, see
108
{url-antora-docs}/cli/options/[Antora CLI documentation].
109
110
111
112

For the preview support, we generate a dedicated Antora playbook based on the production playbook store in the repository
and options passed to the `build-preview.bash`. +
Then, this custom playbook is passed to the Antora CLI along with specific options when needed.
113
114


115
[[local-content]]
116
===== Using local documentation content repositories
117

118
This activates the {url-antora-docs}/playbook/author-mode/[Antora author mode]. +
119
Antora uses the locally cloned repositories as they are on your local machine instead of cloning them from their remote location.
120

121
This provides a fast feedback loop as you don't need to push nor commit sources content. This also makes developments easier when working offline.
122
123
124
125

[NOTE]
.Repositories location
====
126
127
128
129
130
131
This requires to clone content sources repositories locally is the parent folder of this project.
Depending on which sources you use (see the options of the bash script), you may have to clone all, or a part of the repositories
used by the Bonita documentation.

For instance:
----
132
133
root
  |
134
135
136
  -- bonita-cloud-doc
  |
  -- bonita-continuous-delivery-doc
137
  |
138
  -- bonita-doc
139
  |
140
  -- bonita-documentation-site
141
142
  |
  -- bonita-labs-doc
143
----
144
145
====

146
147
148
149
150
151
This can be achieved by running

[source,shell script]
----
./build-preview-dev.bash --local-sources ....
----
152

153
154
155
156
157
158
159
160
161
162
163
164
165
166
===== Using test documentation content

To play with settings, validate the UI Bundle, experiment AsciiDoc syntax and much more, the `bonita-documentation-site` repository provides
a test site structure with documentation content.

The generation site generation is very fast, so using this content reduces the feedback loop.

This can be achieved by running

[source,shell script]
----
./build-preview-dev.bash --use-test-sources ....
----

167
168
169
170
171
[[local-ui-bundle]]
===== Using local UI Bundle

The prebuilt UI Bundle is stored in this repository and sources are located in the https://github.com/bonitasoft/bonita-documentation-theme[bonita-documentation theme]
repository. +
172
173
174
175
If you are developing in the theme repository and want to see the resulting changes in the documentation, you can directly
use the UI Bundle built by the theme repository. +
This provides a fast feedback loop as you don't need to build copy the UI bundle from the theme repository and then run
a build command: everything can be done by running a single command once the push nor commit content as the current work.
176
177

Remember that the theme repository provides a preview with mock content that make development easier. But sometimes, integration
178
tests are required to ensure everything is ok, especially when dealing with {url-antora-docs}/playbook/site-keys/[site keys].
179
180
181
182
183
184

[NOTE]
.Repositories location
====
This requires to clone the theme repository locally is the parent folder of this project.
For instance
185
----
186
187
188
189
root
  |
  -- bonita-documentation-theme
  |
190
  -- bonita-documentation-site
191
----
192
193
====

194
This can be achieved by running
195

196
197
198
199
[source,shell script]
----
./build-preview-dev.bash --local-ui-bundle ...
----
200

201
202
203
204
205
206
For a faster loop, don't forget you can build the UI Bundle and the preview by chaining the commands

[source,shell script]
----
<ui_bundle_build_command> ; ./build-preview-dev.bash --local-ui-bundle ...
----
207

208
209
210
211
212
213
214
215
216
217
218
219
===== Using the Default Antora UI

Sometimes, you need to compare the site rendering with this bundle if you suspect a bug in the Bonita documentation theme.

This can be achieved by running

[source,shell script]
----
./build-preview-dev.bash --default-ui-bundle ...
----

If you want to ensure you use the latest version of the bundle pass `--default-ui-bundle snapshot`. Otherwise, a cache
220
version is used. For more details, see the {url-antora-docs}/playbook/ui-bundle-url/#snapshot[Antora Documentation]
221

222

223
224
225
226
227
===== Quick fix and experiment Antora UI changes directly in the documentation site

If you need/want to experiment changes without rebuilding the theme, especially if the changes only involve the template,
you can directly put the files in the documentation site.

228
See the {url-antora-docs}/playbook/ui-supplemental-files/[Antora supplemental UI] for a complete explanation.
229
230


231
==== http dev server
232

233
234
235
236
237
[NOTE]
====
Most of the time, pages can be browsed locally without requiring a http dev server. +
You may need it to test specific features like displaying Asciinema resources or testing redirects. See below for more details.
====
238
239


240
Once the static site is build, you can run `npm run serve` and access it with `+http://localhost:8080+` to check if everything is working correctly (urls in taxonomy, links, ....).
241
242
243

You can rebuild the site while the server is running, updated files are directly considered by the server (no cache).

244
245
To ensure all links are correctly generated for local deployment, pass the `+--site-url http://localhost:8080+` options
when building the preview.
246

247
248
249
250
251
252
[TIP]
====
A http server is needed to correctly see the Asciinema resources (loading fail when using a local file browsing). +
For instance, have a look at http://localhost:8080/bonita/2021.1/migrate-from-an-earlier-version-of-bonita-bpm#update-case-overview-pages
====

253
254
255
256
257
258
259
260
261
[TIP]
====
The http dev server is provided by the https://docs.netlify.com/cli/get-started/[Netlify CLI], so it is able to replicate a lot of the Netlify Edge features. +
In particular it is able to apply the same redirects as those used in production.

See for xref:docs/configure-netlify-redirects.adoc[configure Netlify redirects how-to] more details.
====


262
263
264
265
266
267
268

=== Production build

WARNING: This is probably something you won't often do as the site is not fully working for local browsing nor for simple http server.

[CAUTION]
====
269
The following command {url-antora-docs}/playbook/runtime-fetch/[fetch the documentation content repositories] each time it runs. +
270
271
See <<non-production-build>> for alternatives.
====
272

273
Run `npm run build`