bonitasoft/bonita-documentation-site

The sources of the Bonita Documentation site

New Bonita Documentation Site

This repository lets you generate the Bonita documentation site. It uses Antora which processes AsciiDoc documentation content stored in various Git repositories.

Documentation

See the dedicated folder for

• documentation content contribution tips/guidelines

• architecture

• maintainers guides

• and much more

More details are available in the Architecture Documentation.

Build

Requirements

Node 16.x (may work with newer versions, no guarantee).

While you can install Node from the official packages, we strongly recommend that you use nvm (Node Version Manager) to install and manage Node. Follow the nvm installation instructions to set up nvm on your machine. Then run nvm use.

ℹ️	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

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 references between pages that belong to different docs components and/or versions

• …​.

To know all available options, run

./build-preview.bash --help

ℹ️	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.

Build a single component version using locally modified document content sources (see required setup)

./build-preview-dev.bash --local-sources \
  --component bonita \
  --branch fix/a_major_documentation_content_fix

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

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.

⚠️	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 references)

For more details, see:

• Configure Antora’s Cache

• Antora Atlas configuration

Using local documentation content repositories

This activates the Antora author mode.
Antora uses the locally cloned repositories as they are on your local machine instead of cloning them from their remote location.

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.

ℹ️

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: root | -- bonita-central-doc | -- bonita-cloud-doc | -- bonita-continuous-delivery-doc | -- bonita-doc | -- bonita-documentation-site | -- bonita-labs-doc

This can be achieved by running

./build-preview-dev.bash --local-sources ....

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

./build-preview-dev.bash --use-test-sources ....

Using local UI Bundle

The prebuilt UI Bundle is stored in this repository and sources are located in the 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 site keys.

ℹ️	Repositories location This requires to clone the theme repository locally is the parent folder of this project. For instance root | -- bonita-documentation-theme | -- bonita-documentation-site

This can be achieved by running

./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

<ui_bundle_build_command> ; ./build-preview-dev.bash --local-ui-bundle ...

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

./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 version is used. For more details, see the 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 Antora supplemental UI for a complete explanation.

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

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 Antora xref documentation:

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 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 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 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 .github/actions/build-pr-site/action.yml to install the latest alpha Antora version.

⚠️	be aware of the cache. Once in cache, the site manifest file is put in cache and is never downloaded again.

http dev server

ℹ️	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.

💡	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

💡	The http dev server is provided by the 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 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:

• shared actions

• reusable workflows: by convention, the reusable workflows are prefixed with reusable

Production build

⚠️	This is probably something you won’t often do as the site is not fully working for local browsing nor for simple http server.

🔥	The following command fetch the documentation content repositories each time it runs. See Non production build for alternatives.

Run npm run build

bonita-documentation-site's Issues

Decide how we are going to manage document of component pre-versions

What is a pre-version and how it is managed in the old doc site

• When development of a new version start, the documentation for this new version is initialized
  It is publicly available but the version is not displayed in the version pick list.
• When the version is in beta, it is made available in the pick list (and displayed as beta) but is not selected by default, it is not the default version
• When the version is GA, update the default

Everything is managed in the documentation site generator project.

To be decided

Antora Default UI features

• everything can be managed in the component documentation repsitory
• displayed version is configurable: https://docs.antora.org/antora/2.3/component-display-version/. So the documentation content repository can configured what has to be displayed (7.13 preview/dev, 7.13 beta, ....)
• prerelease version: https://docs.antora.org/antora/2.3/component-prerelease/. Prerelease are available in the pick list but not considered for the default/latest version computation

Proposition 1: keep the existing behaviour
Possible extension in Antora UI if we want to keep
in the nav-explore.hbs, the version list accesses to the component version elements. We could hide a prerelease version that has custom attributes/properties (if it can access to it, these elements can be configured in the antora config file in the component documentation repository) or if the displayed version contains a specific string (preview, dev).

Proposition 2: switch to Antora default
Is this really a problem to make the documentation of a preview/dev version visible to everybody.

Integrate the Bonitasoft favicon to the generated site

Possible implementation

• Does it to have been part of the custom Antora UI bundle?
• We could also copy it to the folder that store the generated site after the site generation
• manage the file copy with the Antora playbook as this has been done for the 'no jekyll' configuration file (#26)

Check potential md to adoc conversion issue with html anchor

Seen with Bonita 7.5 conversion.

A lot of a anchor are not migrated

Check if we can use font awesome icons or other icons set

Status with the old documentation site

In the old documentation site, it was possible to use font awesome icons.

For instance the BICI index page uses icon with links to release-notes, getting started, ... (https://github.com/bonitasoft/bonita-ici-doc/blob/1bfba7e81f38250e568a5b1a4f29b4b6125f6215/md/index.md)

Same for BCD (https://github.com/bonitasoft/bonita-continuous-delivery-doc/blob/0538a65330f0058f5b3c5f36c3199c0e42529b03/md/index.md)

Same for Bonita Cloud (https://github.com/bonitasoft/bonita-cloud-doc/blob/cf6c2e6d478b40a5ce688d6f76a4b945a7241b82/md/index.md)

To be investigated

Providing icons support helps the documentation to be more attrative, so we should check what we can provide on this side.
This is possible with Asciidoctor (https://asciidoctor.org/docs/user-manual/#icons). See what is possible with Antora.

This may be related to #66

[UPDATE 2022-01-10] https://antora.zulipchat.com/#narrow/stream/282400-users/topic/.E2.9C.94.20font.20awesome. It should work as in a regular AsciiDoc page: declare the icon set as AsciiDoc attribute and use the icon macro: https://docs.asciidoctor.org/asciidoc/latest/macros/icons/

Making the site live: allow robots

docs.antora.org/antora/2.3/playbook/site-robots

Robots have been disallowed while setuping the new site, see #19

Add icons in Admonitions

Various documentation generated with Antora adds icons in Admonitions generated by the Antora default UI bundle

Kroki

kroki also uses Antora, they have put additional icons to NOTE, WARNING, .... https://docs.kroki.io/kroki/setup/usage/ https://docs.kroki.io/kroki/setup/kroki-cli/

Asciidoctor

The asciidoc and asciidoctor official documentation using Antora also display icons, for instance on https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/

Customization example

This example provides a way to customize Admonicon without changing the Antora UI bundle: https://blog.yuzutech.fr/blog/antora-admonitions-icons/index.html.

Provide preview environments to check documentation content changes

How we can check documentation content changes now

For now, we can

• on GitHub, look in the Web UI the Asciidoctor rendering: this allows to detect typo, but as the Asciidoctor support is very limited, some elements are not correctly rendere. Even if it would be better, this doesn't allow to see the final generated site, for instance, it is hard to check the taxonomy.
• for developer, some IDE have Asciidoctor and Antora support, which is better than GitHub. This doesn't help occasional Technical writer.
• generate the site locally: update the Antora Playbook to make it build the branch under work instead of the branch targeted by the changes (the changes can be done locally prior pushing the branch)
• if we had #49, we could push the documentation content changes and then create a doc site PR by changing the Antora Playbook to build the new branches. Again, probably only for developers.

Improvement proposal

When a PR is created on the documentation content repository, the documentation site (at least the part containing the change - component branch) is built and made available on a public site.
If possible

• display the component name, branch or PR number on the site to easily know what changes is displayed.
• put also this information in the url (some solutions allow that)

A lot of solutions exist to host static site: heroku, netlify, https://surge.sh/, vercel, ...
See also #49 to see if we can have a shared solution for both use cases.

Configure Google Analytics

The Antora Default UI provide a way to include Google Analytics script in all pages by just adding a conf entry in the Antora Playbook, see https://docs.antora.org/antora/2.3/playbook/site-keys/#google-analytics-key

Integrate the new Bonita REST API documentation

https://github.com/bonitasoft/bonita-openapi provides an OpenAPI file that can be used to generate the REST API documentation.
We would like to remove the manually maintained REST API documentation from the Bonita documentation and replace it by a new documentation section generated from the OpenAPI resources.

To be discussed

• how do we integrate the new documentation based on OpenAPI? pre-generated content in asciidoctor produced from the OpenAPI spec then registered as an Antora component? produced html by the OpenAPI tooling?
• how do we migrate from the old documentation to the new documentation? mark the old documentation as deprecated and link to the new one? remove the old doc in supported Bonita version

Decide how we will handle documentation content backport

This at least applies to bonita-doc

The current way of fixing/updating the documentation is to perform the change in the oldest supported version, then merge the branch from version to version to propagate the change.
This process is automated using a private solution hosted by Bonitasoft (private CI and private scripts).

Do we continue to do it privately or do we setup a public CI job to manage it?
If we decide to switch to GitHub Actions, implement #12

Document flow to migrate actual markdown content to Asciidoctor

• To test it, use oldest branch on bonita-doc ( 7.3> branch > 7.8). See also #11
• Duplicate branch with a identify name (ex: 7.3_asciidoctor)

Highlight pages related to out of support versions

Goal: explicitly inform users that they are using out-of-support versions and provide a link to the newest version

Old site design

In the old documentation, this was sometimes done by changing the "Fork me on " rubber into "Out of support". On 2020-11-19, this was only available in the Bonita 7.3 documentation
Using the rubber is not the best choice as we use the same design for 2 different things and users associate the rubber to a link for contributions, so don't pay attention to the "out of support" text.

New proposal

Add a specific banner in pages

Let's have a look to the solution provided by the Couchbase Antora UI project: a banner is added to the top of the page and provide a link to the latest available version.
We could use the same logic to have a banner with a warning. A out of support version could be configured in the doc content repository antora configuration file at branch/version level (as an asciidoctor attribute or any other available configuration)

Displayed version

In addition, we could update the display version like proposed in https://docs.antora.org/antora/2.3/component-display-version/#display-version-key: 7.7 EOL
See also #33

Disable the search engine indexation during the migration phase

To be set in the robots.txt.
This will avoid potential content duplication between the new site (currently only available at https://bonitasoft.github.io/) and https://documentation.bonitasoft.com/

Check that the urls are the same as on the previous site

If we don't put redirect rules, we must ensure that urls stay the same to avoid any mess with Search Engine like Google.

See also #24

Documentation that could use version-less/master version (https://docs.antora.org/antora/2.3/component-with-no-version/#version-master):

• bonita-cloud: there is no version for bonita-cloud, url in the old site is https://documentation.bonitasoft.com/cloud/latest/ --> if we have to keep the 'latest' part, we cannot use Antora master version
• bonita-ici: current https://documentation.bonitasoft.com/bici/{version}/ . Depending on the choice Bonitasoft want to do with the content, we should have to manage version as bonita-cloud

In case we have to keep the original url but we do want use 'no version' Antora component:

• Antora discourage the alias usage in case of bulk redirects, https://docs.antora.org/antora/2.3/page/page-aliases/.
• Use webserver/services redirect instead

Decide how to document the Contributing guide for Tech Writers

We should decide this before converting to much documentation content branches, otherwise we will have to go back to the branches afterwards.

How this is done for the old documentation site

Each repository and each branches in the repository duplicates some information that are out-of-date and incomplete. Sometimes there is a link to see how to contribute (markdown tips and how-to) which confer to the Bonita 7.3 branch
At the same place, we have mixed information for Tech Writers and Developers

Proposal for the new doc site

Centralize most information directly in the bonita-documentation-site repository

• always up to date with the Antora and Asciidoctor current way of doing
• single place so avoid duplication and out-of-date content
• focus here on the Tech Writer Documentation Content:
  • we want to have most of external doc content contributors and to make their life easy: let's help them first
  • the Developers in charge of customizing or generating the site are mainly Bonitasoft developers, the documentation can/should be put elsewhere

Tech Writer how-to contributing guide elements

In progress --> managed by #142

• points to Ascidoctor and Antora documentation: no need to recreate some contents
• hightlight some Antora features and when they can be useful for the Bonita Documentation (no need to talk about the 'how', focus on the 'what')
• tips that could be added to this page
  • explain why GitHub may not rendered admonition (https://asciidoctor.org/docs/user-manual/#unicode-admonition-icons)
  • asciinema custom integration (#29)
  • cards (#40)
  • variables/attributes (#54) and how to escape them to avoid Asciidoctor warnings
  • Antora modules to clarify content (for instance, getting-started guides, how-to articles): https://docs.antora.org/antora/2.3/module-directories/#module.

Modules allow to better separate content and resources (for instance specific images and
attachments). For Bonita doc, this will avoid for instance to have all "getting started" pages at
the same level as other pages (currently in the md foler): eaiser to identify what pages and images
are related to "getting started", easier maintenance, ....

We won't be able to move to module right now as the url would changes but at least for new content

• other tips
  • set alias when renaming pages (important for SEO): https://docs.antora.org/antora/2.3/page/page-aliases/. Successfully experimented in bonitasoft/bonita-labs-doc#123
  • examples directory to store source code which can then easily be integrated in the doc https://docs.antora.org/antora/2.3/examples-directory/ We should allow user to download the source as attachments by providing a link directly for the code (no dup between actual examples and doc)
  • reference to documentation pages of another component: for instance, bcd doc has link to bonita doc. To avoid hard coded url, use https://docs.antora.org/antora/2.3/page/page-id/ (see https://opendevise.com/blog/referencing-pages/ for rationale). Warn: won't work with PR preview in the document content repository, as that kind of preview only build a single component version

Legal information

To keep in each repository and branch

• explanation about the CLA and why it has to be signed (we have a sentence in https://github.com/process-analytics/bpmn-visualization-js/blob/v0.8.0/docs/contributors/pull-request.md#sign-the-contributor-license-agreement which has been created after discussions with the Bonitasoft lawyer)

Move already work done on Adrien repo here

Initialize this repo with work done on https://github.com/alachambre/antora-playbook-test

Create GitHub repositories for bonita-documentation site and theme

Add possibility to switch from ☀️ to 🌑 theme

Improve UI layout

• Centered UI
• Remove duplication to switch version
• Dedicated place for the searchbar (where?)

Defects:

• Orphan menus collapse when resizing the screen
• The search bar is to big in phone size (will probably be addressed when w'll work on the search bar design).

Provide preview environments to check documentation structure changes

The production site is deployed on GitHub pages which only provide a single 'production' environment.

When we create a PR to change the site structure (Antora UI, Antora playbook configuration), we currently can only tests the resulting generated site by downloading an artifact and open it locally.
But this is not very convenient to test changes on mobile: we have to expose the site through a local server.

Having a preview live environment would allow to test mobile easily, share an url for quick evaluation by anyone without having to setup anything.
See also #50 to see if we can have a shared solution for both use cases.

Check and evaluate if we could use ElasticSearch to replace Algolia

Let's start with the assumption that it will be Elastic as Service to compare

Decide and document commit conventions

What conventions do we want to use:

• https://www.conventionalcommits.org/en/v1.0.0/
• other
• when merging PR because we want to only squash PR?

Once dediced

• document it in the Contrib Guide

Cleaning document content branches still using markdown

Prior starting the real 'put the site live', the branches (except the ones related to product version - so feature branches) still using the markdown syntax must be managed.

There are a lot of old branches still alive. For instance, on 2021-01-13, there are 47 branches in bonita-doc (https://github.com/bonitasoft/bonita-doc/branches/all)
Some of them cannot be deleted for now, because there are considered as protected because of a branch pattern that is not restrictive enough (we only want to protect branches that exactly match product versions).

For branches related to opened PR, we can ask people to merge them prior the migration. Otherwise, they will have to recreate them or migrate them manually.

Manage the real switch from the current doc-site and new site

Talk with IT to manage the real switch (Who /when/how)

Initialize bonita-documentation-theme

Initialize bonita-documentation-theme with https://github.com/alachambre/antora-ui

Ensure we have 404 error page in the published site

Resources

• Antora can generate 404 html page directly integrated with the documentation site: https://docs.antora.org/antora/2.3/add-404-error-page/
• GitHub Pages provides support for custom 404 error page: https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site

Tasks

• test 404 error page with GitHub Pages: see #37 (comment)
• ensure that Antora generates a 404 page: true as far as a site.url key is defined in the Antora playbook and the Antora UI bundle has a dedicated template. Ok with #23 and the current UI bundle.

Setup continous integration

Setup Github action to:

• build the site
• push it to github pages

when

• on push on bonita-doc content branch, trigger build here to push directly on the production
• Push on the right branch to put it on "production"

A poc has been done with 2 repositories to manage triggering a workflow stored in a repository from workflow located in another repository

• https://github.com/bonitasoft-labs/simulation-of-bonita-doc to simulate a documentation content repo
• https://github.com/bonitasoft-labs/bonita_doc to simulate the documentation site

For site generation and push to gh-pages in a GitHub workflow, we can have a look at https://github.com/process-analytics/bpmn-visualization-js/blob/v0.7.0/.github/workflows/generate-documentation.yml

Pending questions

Do we run a build when the master branch of this repo is updated
probably yes to ensure new theme or antora playbook changes are used
Should not been run on documentation changes (use exclude path)

Do we run a build when PR targeted master are created?
In that case, we could build the site with the local profile and attach it as workflow artifacts. The resulting site could be then tested locally after having been downloaded
In the future, we could deploy the generated site on a public free solution (netlify, vercel, heroku, ...)

Migration tool: dedicated repository or branch for release-notes

In current site, there is a release notes pages that is duplicated accross all bonita doc supported versions.
This require branch merges and maintenance which is a pain.

With the new documentation powered by Antora, we could have a dedicated migration tool section for displaying release notes, backed by

• a dedicated branch in the bonita-doc repository, containing a new migration component with no version
• a dedicated repository

Disallow robot during development of the new solution

Rationale: the documentation site will be available at https://bonitasoft.github.io/ during development in parallel to https://documentation.bonitasoft.com/. We want to avoid duplicated content detection by search engine.

See https://docs.antora.org/antora/2.3/playbook/site-robots/

Find a way to not be forced to store the Antora UI bundle in the repository

Currently, after each changes and rebuild from the https://github.com/bonitasoft/bonita-documentation-theme we want to use in the documentation site, we have to store the new zip file in the repository.

Let's check if we can store it in a remote storage and retrieve it when generating the site.
See also https://docs.antora.org/antora/2.3/playbook/ui-bundle-url/

Potential targets

• assets of a GitHub release
• GitHub package
• ....

Tasks

• Choose the solution: #47 (comment)
• Implement it: bonitasoft/bonita-documentation-theme#107 and #366
• Update the procedure about the theme release and update in the git repository (this is located in the README of the theme repository): bonitasoft/bonita-documentation-theme#107
• when the Antora configuration will use the bundle from the documentation-theme GitHub release, remove the former ui-bundle.zip file previously stored in the repository. This can be done in the 1st pull request that will use the GH release asset. See #369

Update UI footer (Antora default UI stuff).

Build: check if we can rebuild only a part of the site

This may be useful if

• the whole generation is too long (fetch + generation)
• we want to limit changes committed to gh-pages

Possible implementations

TO BE DISCUSSED and probably tested

Proposal 1

If possible, we could also only rebuild a single branch.

Proposal 2

Rebuild all
In the gh-pages branch, commit/push only the component version (folder including the version) which has changed + probably the related sitemap file
We could also detect the changed asciidoctor source file and only commit the related html file

Tasks

Investigations

• do we really need it (performance, too much touched files)?
• poc what could be the best solution

Tasks if we want to do it

• check if Antora provide ways to do it
• provide new build scripts options for this site generation
• update the GH workflow (on worflow_dispatch) to only build the component passed as input (this requires #45)

Prepare github-pages publish

We are going to published the generated static sites to GitHub pages.
We can start doing this prior configuring automation with #5

• ensure noJekyll, see https://docs.antora.org/antora/2.3/publish-to-github-pages/#use-the-supplemental-ui --> #26
• robots disallowed, see #19
• sitemap configuration review
• urls without html extension review
• setup gh-pages branch: orphan branch created and configured as protected, initial index.html created
• 1st manual push of the generated site to gh-pages to make a 1st version of the site available at https://bonitasoft.github.io/. Once #17 and #26 have been merged

Search bar integration

Document targeted Architecture

A global schema should be nice

To be reviewed with final decision

• search: Algolia + indexation
• deployment/hosting: GH pages Netlify
• doc source: 1 gh repo per component + branches
• site generation: site repo with Antora
• build automation: gh actions
• preview

Investigate what we can do with github-pages custom domain

This will cover a part of #6
See https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site

Questions

• Can we try to use beta.documentation.bonitasoft.com while we are developping the new site?

Start Migrating bonita-ici-doc content

The content of this repository can be migrated right now

• we only want to keep a single version
• the documentation content will be based on the 1.3 version content and later adjusted incrementally

Tasks

• create a master branch from 1.3 and migrate content, see bonitasoft/bonita-labs-doc#118
• integrate bici as part of the documentation site, see #17
• setup GH workflow jobs in the bonita-ici-doc (covers #5), see bonitasoft/bonita-labs-doc#119

Note
Once this is done, the content of the repository will be updated by content contributors.
This will

• let us validate the workflow
• let external non technical people use the solution
• allow to incrementally update the BICI doc content to be consistent with a single documentation version

Integrate the Bonita Javadoc static resources

Remark: this is something similar to what we could need for #39.

The javadoc is currently available via url like http://documentation.bonitasoft.com/javadoc/api/7.11/index.html and is not part of the documentation content repository. It is pushed directly on the server.
Note: We also have groovy doc

Possible solutions (to be discussed, non exhaustive list)

• do not publish the javadoc:
  • pros: already available in another ways, in particular in developer IDE
    • community: already available via https://javadoc.io/doc/org.bonitasoft.engine/bonita-client/latest/index.html and available on maven central as javadoc jar. Also available for dedicated version: https://javadoc.io/doc/org.bonitasoft.engine/bonita-client/7.11.4/index.html
    • enterprise: available from the Bonitasoft Customer Portal as javadoc jar
  • cons
    • no more all-in-one Community/Enterprise Javadoc as the one currently published in the documentation
• push the javadoc to a dedicated repository that will host a gh-pages branch. For instance, in the https://github.com/bonitasoft/bonita-platform-releases repository
  • pros
    • this repository is already managed by the Bonitasoft IT Team which is currently in charge of publishing the javadoc to the documentation site
    • this would keep the main documentation only generated by Antora: we can easily recreate from scratch, don't have to manage deletion or move manually
    • avoid growing the site size: already 359 MB in 2a0a6fd
• push the javadoc directly at the same place as the rest of the documentation and manage links in the documentation
  • pros: easy to update, no extra antora configuration
  • cons: out of the rest of the generate site, we can not create a fresh environment, clean the existing gh-pages (so files deletion will have to be managed manually). This may have been possible when we were deploying to gh-pages as we can update the content of the branch, for netlify, this would require extra step to aggregate the generated content with the javadoc content and push everything at the same time and every time the doc content changes
• create a javadoc Antora component and store the static file in a dedicated branch of bonita-doc or in a new repository

questions

Urls to the javadoc

At 1st glance, the javadoc url could change as they are not supposed to be indexed so we shouldn't be forced to keep the original urls.
When we will have redirect capabilities (#117), we will be able to put redirect from old redirect to new one (or if needed, setup rewrite rules)

Links to javadoc

Note: this is independent of the choosen hosting solution

how do we set links to javadoc in the source documentation content. Currently, the url is hard coded and the version is managed via a variable (see also #54). We could use a single Asciidoctor attribute that contains the full url.

Decide how we redirect users to pre Bonita 7.3 documentation

In the old documentation site, the Bonita 7.2 and before documentation version is displayed in the version pick list as shown in the above screenshot.

When clicking on such versions, a modal is displayed and the user is redirected to the Legacy documentation website

We don't have this by default with Antora UI so we can

• reimplement the existing behaviour
• provide an alternative

See also #33.

Antora Resources that may help

• example that shows versions on the list (top bottom of the page) that point to external url: https://antora.gitlab.io/antora-ui-default/#some-code generated from https://gitlab.com/antora/antora-ui-default
• this repos doesn’t use external repositories for source as it doesn’t run antora cli to build the static site. It uses the https://gitlab.com/antora/antora-ui-default/-/blob/master/preview-src/ui-model.yml as config file and doc sources from the preview-src folder

Fix theme vulnerabilities

Check potential md to adoc conversion issue with tables

During the initial BICI conversion (#17), we have detected that the tables in the rest api documentation were not correctly migrated, but those in the prerequisites page were correctly converted.
This may be an issue in the md sources: the rest api md files are generated, so maybe the syntax is not fully correct, the old generation system is able to convert them but not kramdoc.

So we have to be careful when doing conversion review for pages that contain tables.

Find a alternative to tables in the component index pages in the generated documentation

The problem

In the old documentation site, the index/home page of each component were using inline html content directly in the markdown source.
For now, this content cannot be converted correctly into Asciidoctor automatically. This problem is documented in the conversion step documentation initiated with #17

This is what the old site currently displays

Bonita	Bonita Cloud

BCD	BICI

Possible solutions to be checked

• find a native way with Asciidoctor and/or Antora default UI to do something similar
• includes html with Asciidoctor includes: https://stackoverflow.com/a/50682699
• migrate the content manually and use html blocks: https://asciidoctor.org/docs/user-manual/#pass-blocks
• see how couchbase handle it: https://raw.githubusercontent.com/couchbase/docs-server/release/6.6/modules/introduction/pages/intro.adoc see screenshot below
• see also #36 for font awesome icons displayed in the index/home pages

Couchbase doc home page with a kind of tables

Limit the number of changes when pushing to the deploy environment

Goals of this improvements

• limit the number of changes when committing to the gh-pages branch to better track what changes in production. Notice that #45 will also help to have a better tracking
• reduce history so the repository size

See also #46 for more details.

Sitemap files extra changes

We already have identified that the sitemap files are going to be updated very often if we rebuild the whole site. For instance

• on full site rebuild without content nor site configuration changes (9970601), the dates in the sitemap file have changed whereas no html files have been commited
• on a single documentation content page change (efb3d65), all dates is the sitemap have changed as well

We currently (f599811) always clean the Antora build directory when building locally and GitHub Workflow always use a fresh environment, so we don't keep any previous generated files.
We may test if keeping previously generated files change the way the sitemap are generated.
If so, for the GitHub actions, we may keep a cache for the master branch

Find a way to manage variables in the documentation content

In the previous doc site, we were able to use variable in the documentation that were defined in a json file.
For instance, this is used by Asciinema resources - varVersion (see also #29) or BCD used it to declare the Bonita version to target (bonitaDocVersion, see bonitasoft/bonita-continuous-delivery-doc@7ed78d2).

Asciidoctor allows to configure custom properties/attributes in the page, let's check what Antora provides on this side.
For now we have warning when the variables are encountered:

asciidoctor: WARNING: skipping reference to missing attribute: varversion

Notice that we have warnings for elements considered as variables in the documentation, mainly in Bonita Rest API documentation

asciidoctor: WARNING: skipping reference to missing attribute: page
asciidoctor: WARNING: skipping reference to missing attribute: count
asciidoctor: WARNING: skipping reference to missing attribute: order
asciidoctor: WARNING: skipping reference to missing attribute: query
asciidoctor: WARNING: skipping reference to missing attribute: filter_name
asciidoctor: WARNING: skipping reference to missing attribute: filter_value

Tasks

• find a solution, see #54 (comment). Confirmed in #56
• Check if we can escape the elements wrongly considered as variable. If this is possible, update the conversion documentation and try to fix this during the conversion process
  • escape with backslash: https://asciidoctor.org/docs/asciidoc-writers-guide/#preventing-substitution
  • can we have a script that escape elements except the variables we really want to use? yes, done in a python script used to help during the conversion
• check if we need a starting $ character. It seems that javadoc links (they use the varVersion attribute) are not generated correctly and contains a $ character. --> no, we have to remove it
• document everything in the conversion content (md to adoc) guide

Setup an automatic documentation content update from version to version

Note: to be implemented only if decided in #21

In the old documentation solution, this done by a private CI.
This could be done by Github Actions on each content documentation repository

Add support for asciinema

Information and conversion procedure from previous poc

The kramdoc tool is unable to convert asciinema content and generates error, for instance, with file like Bonita migrate-from-an-earlier-version-of-bonita-bpm.md

<script type="text/javascript">
function loadCSS(filename){
    let file = document.createElement("link");
    file.setAttribute("rel", "stylesheet");
    file.setAttribute("type", "text/css");
    file.setAttribute("href", filename);
    document.head.appendChild(file);
}
loadCSS("./assets/asciinema-player.css");
</script>
<asciinema-player src="bonita/images/${varVersion}/case_overview_update_mode-ascii.cast" speed="2" theme="monokai" title="Update case overview console output example" cols="240" rows="32"></asciinema-player>
<script src="./assets/asciinema-player.js"></script>

Workaround for the conversion procedure

• prior migrating, comment the asciinema block in the md file
• convert to asciidoctor
• in the converted file, replaced the commented block (surrounded by '////'):
  • replace the / characters by + (you should have some ++++ at the end of the block a)
  • for more information, see https://asciidoctor.org/docs/user-manual/#pass-blocks
• update the path to sources (js, css et .cast):
  • “./assets/asciinema-player.css” → "/_attachments/asciinema-player.css"
  • “bonita/images/${varVersion}/case_overview_update_mode-ascii.cast” → “_images/images/case_overview_update_mode-ascii.cast”
  • "./assets/asciinema-player.js" → "./_attachments/asciinema-player.js"
• create a new folder modules/ROOT/assets/attachments and copy the asciinema-player.js et asciinema-player.css that are currently only available in the private documentation site gnerator repository
• ensure that the ascinema source file (.cast extension) exist in the images folder: for instance, modules/ROOT/assets/images/images/case_overview_update_mode-ascii.cast

Work to do

New Investigations to be conducted

• There is currently no Asciidoctor native support for asciinema, see asciidoctor/asciidoctor#1798, let's see if there is some in Antora or if we can contribute one (maybe later)
• See if the asciinema attachments files can be made available through the antora-ui bundle (documentation theme) to avoid duplicate the asciinema resources in all repositories. This will also prepare the real integration when available

Tasks (to be extended depending on the chosen solution)

• document the solution in the content documentation conversion guide
• document the solution in the tech writer contributing guide to let user know how they can integrated asciinema resources in the doc site (see #52)

Add license to repositories

• Decide which license to use
• store license in https://github.com/bonitasoft/bonita-documentation-site. Also update the package.json file. See #28
• store license in https://github.com/bonitasoft/bonita-documentation-theme. Must be MPL-2.0 as this is derived from antora-ui. See bonitasoft/bonita-documentation-theme@0f59de1

Decide how we show out-of-support versions in the versions pick list

In the current documentation site, out-of-support versions are in a submenu of the versions list of a component.

We don't have this by default with Antora UI but we also expect to be able to better identify pages related to out-of-support versions, see also #22.

We should decide if

• we keep the same display as in the old doc site
• we use the Antora default: all versions available without distinction, we can also renamed the displayed version to better identified it is out-of-support (see #22 proposal for instance, like 7.7 EOL)
• we propose something else

Check if we can have current/latest version urls

In the old site, we could use https://documentation.bonitasoft.com/bonita/latest/ or https://documentation.bonitasoft.com/bcd/current/ (in fact, any string instead of a version) and we were reaching the latest version of the component documentation.

Let's see if we can do the same with the new site.
Generally, this is manage with a redirect rule configured in the http server. It seems that the Couchbase doc has implementated something in the antora ui/theme part to provide something on that field: see https://github.com/couchbase/docs-ui/blob/v269/README.adoc#view-latest-and-canonical-url

Alternative proposal: use latest instead of named version for the newest supported version

If we can have a redirect of latest to a named version we could do the following example

• We assume here that the newest supported version is 7.12
• in the 7.12 branch, the key version would be latest and the displayed version 7.12: the url contains latest instead of 7.12` and the pages display the expected version
• when the 7.13 version goes GA,
  • we update the 7.12 branch: the key version becomes 7.12 and is then available with the 7.12 urls
  • in the 7.13 branch, the key version is set to latest, and the neweset version is then available through the latest url

This requires more work on Product GA and we should see if we have issues on the SEO side.

CI Workflow: allow to pass documentation component name and branch

Improvement of #5

We would like to have this information to be able to detect which documentation content component triggers a build.
This will allow us to have a better message when committing to the gh-pages branch and let us track the reason of the commit.
In the future, we may also be able to only rebuild the component that is passed as inputs of the request (see #46).

Proposal

Add inputs to the workflow_dispatch configuration (see #5 for repositories we used to poc such a solution)

Commit messages

• push on master branch: deploy <commit> as today
• workflow_dispatch manual: don't set the doc component info --> deploy <commit> from manual request
• workflow_dispatch from doc component: pass the info in the event --> deploy <component> <branch> update