Newer
Older
= New Bonita Documentation Site
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
// External URIs:
:url-antora: https://antora.org
:url-antora-docs: https://docs.antora.org/antora/3.1
Thomas Bouffard
committed
:url-asciidoc: https://docs.asciidoctor.org/asciidoc/latest/
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation
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]
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]
This repository lets you generate the Bonita documentation site. It uses {url-antora}[Antora] which processes {url-asciidoc}:[AsciiDoc]
documentation content stored in various Git repositories.
== Documentation
See the xref:docs/README.adoc[dedicated folder] for
* documentation content contribution tips/guidelines
* architecture
* maintainers guides
* and much more
More details are available in the xref:docs/architecture.adoc[Architecture Documentation].
== Build
=== Requirements
The build requires {url-node}[NodeJS].
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. Then run `nvm use`.
If you wish to install NodeJS in another way, make sure you install the version defined in the xref:.nvmrc[.nvmrc] file.
[NOTE]
====
* all commands are intended to be run from the repository root folder.
* the generated documentation is available in the `build/site` folder.
====
Don't forget to run `npm install` the first time you build the project or on `package.json` changes.
Check that the `Antora` CLI is available by calling `npx antora --version`.
[#non-production-build]
== Non production build
[[preview]]
=== Preview support
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.
This includes building the documentation using:
* already checkout local documentation content repositories
* single branch for all components
* single branch of a single component
* 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]
* ....
To know all available options, run
[source,shell script]
----
./build-preview.bash --help
----
[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
{url-antora-docs}/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.
[[content-cache]]
===== Documentation content cache
By default, without passing any specific options to the CLI relating to the documentation content, the resources are only fetched
once from the remote locations and then cached in the `.cache` directory.
WARNING: This cache is not updated except if you specify it to the CLI by passing the `--fetch-sources` option.
You may need to update the cache if you want to retrieve a fresher version of the content. For instance, to get new branches related to new documentation versions,
or newer content of existing versions.
Resources put in the cache:
* documentation content git repository
* ui-bundles (Bonita and default themes)
* Antora Atlas site manifest (use to <<validate-reference, validate references>>)
For more details, see:
* {url-antora-docs}/page/cache/[Configure Antora’s Cache]
* https://gitlab.com/antora/antora-atlas-extension#user-content-configure[Antora Atlas configuration]
[[local-content]]
===== Using local documentation content repositories
Thomas Bouffard
committed
This activates the {url-antora-docs}/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.
Thomas Bouffard
committed
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.
Thomas Bouffard
committed
[NOTE]
.Repositories location
====
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:
----
Thomas Bouffard
committed
root
Thomas Bouffard
committed
|
-- bonita-cloud-doc
|
-- bonita-continuous-delivery-doc
Thomas Bouffard
committed
|
Thomas Bouffard
committed
|
Thomas Bouffard
committed
-- bonita-documentation-site
|
-- bonita-labs-doc
----
Thomas Bouffard
committed
====
This can be achieved by running
[source,shell script]
----
./build-preview-dev.bash --local-sources ....
----
Thomas Bouffard
committed
===== 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 ....
----
[[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. +
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.
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 {url-antora-docs}/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
----
root
|
-- bonita-documentation-theme
|
Thomas Bouffard
committed
-- bonita-documentation-site
----
====
This can be achieved by running
[source,shell script]
----
./build-preview-dev.bash --local-ui-bundle ...
----
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 ...
----
Thomas Bouffard
committed
===== 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 <<content-cache, cache>>
version is used. For more details, see the {url-antora-docs}/playbook/ui-bundle-url/#snapshot[Antora Documentation]
===== 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.
See the {url-antora-docs}/playbook/ui-supplemental-files/[Antora supplemental UI] for a complete explanation.
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
For articles explaining use cases using supplemental files, see
* http://www.northwestopendata.org.uk/nwod/blog/convert_blog.html
* https://lightbend.github.io/antora-supplemental-ui-lightbend-theme/build/site/index.html
[[validate-reference]]
=== Reference validation and partial build
Reference validation, which covers xrefs, includes, and images, is performed automatically when Antora runs.
The validation errors are shown in the log output, and the build of the Bonita documentation site is configured to enforce reference validation.
Each message shows the repository source, the refname, and the path from the root of that repository.
....
[14:29:22.246] ERROR (asciidoctor): target of xref not found: :do-not-exist_for_sure.adoc
file: modules/ROOT/pages/index.adoc:7
source: https://github.com/bonitasoft/bonita-doc.git (branch: ci/simplify_xref_validation)
[14:29:22.247] ERROR (asciidoctor): target of xref not found: 3.6@bcd::do-not-exist_for_sure-in-bcd.adoc
file: modules/ROOT/pages/index.adoc:9
source: https://github.com/bonitasoft/bonita-doc.git (branch: ci/simplify_xref_validation)
....
==== Reminder: What is a xref?
For more details, see the {url-antora-docs}/page/xref/[Antora xref documentation]:
[quote]
An AsciiDoc xref macro is used to create a source-to-source cross reference from a resource to a publishable resource. The term cross reference, which is often abbreviated to xref, means to use the AsciiDoc xref macro to reference the source file of a publishable resource
For more details about using xref in the documentation content, see the xref:docs/content/CONTRIBUTING.adoc[contributing guide].
==== Partial build and reference validation
When doing a partial build (i.e. not building the whole site), some cross-references between component versions may fail as the target resources are not available.
The https://gitlab.com/antora/antora-atlas-extension/[Antora Atlas extension] provides a way to work around this issue by making the references available while validating.
This is done using a site manifest, in two steps:
* export the site manifest. The export is always enabled and the file is published in production at the same place as the rest of the site content
* import the site manifest. It is enabled xref:scripts/generate-content-for-preview-antora-playbook.js[automatically] when partially building the site with the `./build-preview.bash` script. The site manifest file is downloaded from the production site
==== Special local configuration to use the "import" feature
The Antora Atlas extension is currently in alpha, and it requires an alpha version of Antora (3.2 line) to work.
However, we use a stable 3.1 Antora version to build the site. We don't want to rely on an alpha version that is more rarely updated and not always includes all bug fixes. +
So, a special configuration must be put in place to make the Atlas extension work to manage the xref validation.
Reference validation is done in a specific GitHub workflow when validating PR in documentation content repositories. It calls a dedicated action that handles the special configuration.
To locally use the Atlas extension for reference validation, do the same as in xref:.github/actions/build-pr-site/action.yml[] to install the latest alpha Antora version.
WARNING: be aware of the <<content-cache, cache>>. Once in cache, the site manifest file is put in cache and is never downloaded again.
[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.
====
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, ....).
You can rebuild the site while the server is running, updated files are directly considered by the server (no cache).
To ensure all links are correctly generated for local deployment, pass the `+--site-url http://localhost:8080+` options
when building the preview.
[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
====
[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.
====
=== Shared CI resources
This repository contains shared resources used by the GitHub Actions workflows of the "documentation content" repositories.
Be aware that they are used by referencing the `master` branch of this repository, so any changes pushed to the `master`
branch impact all "documentation content" repositories. So double check prior changing the reusable workflows and shared actions!
Shared resources are:
* xref:.github/actions/[shared actions]
* xref:.github/workflows/[reusable workflows]: by convention, the reusable workflows are prefixed with `_reusable_`
=== 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 {url-antora-docs}/playbook/runtime-fetch/[fetch the documentation content repositories] each time it runs. +
See <<non-production-build>> for alternatives.
====
Run `npm run build`