README.adoc 7.36 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 12 13 14 15 16
// External URIs:
:url-antora: https://antora.org
:url-asciidoctor: https://asciidoctor.org/
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation

17 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 20 21

*_DISCLAIMER: this is a work in progress._*

22 23
This repository let you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoctor}:[Asciidoctor]
documentation content stored in various Git repositories.
24 25


26 27 28 29 30 31 32 33
== Documentation

See the xref:./docs/README[dedicated folder] for

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

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

37 38 39 40 41 42 43 44 45 46 47

== Build

=== Requirements


{url-node}[Node 12.x] (may work with newer versions, no guarantee). For more details, see the  https://docs.antora.org/antora/2.3/install-and-run-quickstart/[Antora installation guide].

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.
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.

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

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

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


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

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

65 66
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.
67

68
This includes building the documentation using:
69

70 71 72 73 74
* already checkout local documentation content repositories
* single branch for all components
* single branch of a single component
* a set of branches of various components. This is let validate https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/[references between pages that belong to different docs components and/or versions]
* ....
75

76 77 78 79 80
To know all available options, run
[source,shell script]
----
./build-preview.bash --help
----
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 108 109 110 111 112 113
[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
https://docs.antora.org/antora/2.3/cli/options/[Antora CLI documentation].

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.
114 115


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

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

122
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.
123 124 125 126

[NOTE]
.Repositories location
====
127 128 129 130 131 132
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:
----
133 134 135 136 137 138
root
  |
  -- bonita-doc
  |
  -- bonita-ici-doc
  |
139
  -- bonita-documentation-site
140
----
141 142
====

143 144 145 146 147 148
This can be achieved by running

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

150 151 152 153 154
[[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. +
155 156 157 158
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.
159 160 161 162 163 164 165 166 167

Remember that the theme repository provides a preview with mock content that make development easier. But sometimes, integration
tests are required to ensure everything is ok, especially when dealing with https://docs.antora.org/antora/2.3/playbook/site-keys/[site keys].

[NOTE]
.Repositories location
====
This requires to clone the theme repository locally is the parent folder of this project.
For instance
168
----
169 170 171 172
root
  |
  -- bonita-documentation-theme
  |
173
  -- bonita-documentation-site
174
----
175 176
====

177
This can be achieved by running
178

179 180 181 182
[source,shell script]
----
./build-preview-dev.bash --local-ui-bundle ...
----
183

184 185 186 187 188 189
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 ...
----
190

191 192


193 194 195

==== http server

196
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, ....).
197 198 199

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

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

203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
[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
====


=== 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]
====
The following command https://docs.antora.org/antora/2.3/playbook/runtime-fetch/[fetch the documentation content repositories] each time it runs. +
See <<non-production-build>> for alternatives.
====
219

220
Run `npm run build`