Unverified Commit 387ecb79 authored by Thomas Bouffard's avatar Thomas Bouffard Committed by GitHub
Browse files

Merge branch 'master' into chore/simplify_start_page_settings

parents 0941b7b5 a080cea1
......@@ -4,21 +4,21 @@ We are pleased to receive any kind of contribution (issues, pull requests, sugge
== Commit message format
Here is the expected commit format, please follow https://www.conventionalcommits.org/en/v1.0.0/[conventional commits rules]. We give you a little summary about basic commit templating message.
Here is the expected commit format, please follow https://www.conventionalcommits.org/en/v1.0.0/[conventionnal commits rules]. We give you a little summary about basic commit templating message.
```
[source]
----
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
----
== Pull request
Each improvment, fix must be submit with a pull request. When a pull request is submit, a action is running to check if your pull request follow commit message format.
For each improvement, the fix must be submitted with a pull request. When a pull request is submitted, an action is run to check if the pull request follows the commit message format.
== Intregration policy
== Integration policy
By default, all pull requests is squash when Maintainer has validated your contribution. If you don't want squash your commit, please tell us by a comment in your pull request.
......@@ -19,10 +19,18 @@ image::https://api.netlify.com/api/v1/badges/df65c069-bb52-46d2-8bf0-8e16b6b2148
*_DISCLAIMER: this is a work in progress._*
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.
== Architecture
Static site generation based on {url-antora}[Antora] using {url-asciidoctor}:[Asciidoctor] documentation content stored in various Git repositories.
== Documentation
See the xref:./docs/README[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].
......@@ -37,58 +45,91 @@ More details are available in the xref:docs/architecture.adoc[Architecture Docum
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.
NOTE: all npm commands are intended to be run from the repository root folder.
=== Build the static site for production
[NOTE]
====
* all commands are intended to be run from the repository root folder.
* the generated documentation is available in the `build/site` folder.
====
Run
```bash
npm install
npm run build
```
The static site is then 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 `./node_modules/.bin/antora --version`.
=== Local development
The `antora` CLI is available by calling `./node_modules/.bin/antora --version`
[#non-production-build]
== Non production build
For more CLI options, see https://docs.antora.org/antora/2.3/cli/options/
[[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.
==== Building for local developments
This includes building the documentation using:
[WARNING]
====
The following command https://docs.antora.org/antora/2.3/playbook/runtime-fetch/[fetch the documentation content repositories] each time they are run. +
<<local-content>> or <<preview>> can prevent this to happen.
====
* 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]
* ....
To know all available options, run
[source,shell script]
----
./build-preview.bash --help
----
For a site that can be load from local disk
```bash
npm run local:build-static
```
[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.
For a site to be served by the development <<http server>>
```bash
npm run local:build
```
[[local-content]]
===== Using local documentation content repositories
==== Using local documentation content repositories
This activates the https://docs.antora.org/antora/2.3/playbook/author-mode/[Antora author mode]. The local content of the
repository is used instead of fetching the remote one.
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.
It provides a fast feedback loop as you don't need to push nor commit content as the current work
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.
[NOTE]
.Repositories location
====
This requires to clone all repository sources locally is the parent folder of this project.
For instance
```
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-doc
......@@ -96,22 +137,25 @@ root
-- bonita-ici-doc
|
-- bonita-documentation-site
```
----
====
For more information about the `build-preview.bash` script, see later in this document
```bash
./build-preview.bash --ci false --type local --local-sources true
```
This can be achieved by running
[source,shell script]
----
./build-preview-dev.bash --local-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. It provides a
fast feedback loop as you don't need to push nor commit content as the current work.
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 https://docs.antora.org/antora/2.3/playbook/site-keys/[site keys].
......@@ -121,45 +165,56 @@ tests are required to ensure everything is ok, especially when dealing with http
====
This requires to clone the theme repository locally is the parent folder of this project.
For instance
```
----
root
|
-- bonita-documentation-theme
|
-- bonita-documentation-site
```
----
====
For more information about the `build-preview.bash` script, see later in this document
```bash
./build-preview.bash --ci false --type local --local-ui-bundle true
```
This can be achieved by running
[[preview]]
==== Building for preview
[source,shell script]
----
./build-preview-dev.bash --local-ui-bundle ...
----
It is possible to use a script that let's generate the documentation partially or with specific settings for both local
developments or Pull Request previews.
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 ...
----
This includes building the documentation using:
- already checkout local documentation content repositories
- single branch for all components
- single branch of a single component
- ....
To know all available options, run
```bash
./build-preview.bash --help
```
==== http server
Once the static site is build, you can run `npm run serve` and access to http://localhost:8080/ to check if everything is working correctly (urls in taxononmy, links, ....).
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.
== Documentation
[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.
====
See the xref:./docs/README[dedicated folder].
Run `npm run build`
#!/usr/bin/env bash
########################################################################################################################
# Set convenient defaults for local development usage of the `build-preview.bash` script
########################################################################################################################
set -euo pipefail
devArgs="--type local --ci false"
echo "Running 'build-preview' with dev arguments (${devArgs})"
./build-preview.bash "${devArgs}" "$@"
......@@ -7,27 +7,43 @@ set -euo pipefail
function usage() {
launch_command=$(basename "${0}")
echo "Usage: ${launch_command}"
echo " Globals"
echo " --help Display this help"
echo "Usage: ${launch_command} <options>"
echo "Build the documentation site preview."
echo ""
echo "For 'boolean' options, you can only pass the options when you want to set it to 'true'."
echo "i.e '--force-production-navbar' is equivalent to '--force-production-navbar true'."
echo ""
echo "Options priority order for choosing the content of the preview when several options are provided:"
echo " - use-all-repositories"
echo " - single-branch-per-repo"
echo " - use-multi-repositorie"
echo "If no specific options: single branch per component"
echo ""
echo "Globals"
echo " --help Display this help"
# most of the arguments in this section are used by the nodejs script
echo " Antora configuration"
echo " --branch <branch-name> Name of the branch when keeping a single branch per component"
echo " --component <component-name> Name of the component when keeping a single branch per component"
echo " --fetch-sources <boolean> 'true': fetch documentation content sources prior building the documentation. Defaults to 'false' (on CI, fetch is always done)"
echo " --force-production-navbar <boolean> 'true': use the regular navbar instead of the preview one. Defaults to 'false'"
echo " --hide-edit-page-links <boolean> 'true': hide all edit page links (useful when generating documentation archive). Defaults to 'false'"
echo " --hide-navbar-components-list <boolean> 'true': hide components list in navbar. Defaults to 'false'"
echo " --local-sources <boolean> 'true': use locally checkout sources in a working directory along the one of this project (useful to test local changes without push) , otherwise, use antora cache. Defaults to 'false'"
echo " --local-ui-bundle <boolean> 'true': use locally build ui bundle whose sources are in a working directory along the one of this project, otherwise, use antora cache. Defaults to 'false'"
echo " --pr <PR_NUMBER> Number of the Pull Request related to the preview (when apply). Used to display context information within the preview."
echo " --single-branch-per-repo <boolean> 'true': only keep the latest declared branch for each component, 'false': use all branches. Defaults to 'false'"
echo " --site-url <url> Custom Url of the site preview. If set to 'DISABLED', remove the site.url from the Antora playbook. Defaults to the original url defined in the Antora playbook."
echo " --site-title <string> Title of the site preview. Use generated title if not set."
echo " --type <string> If set to 'local', use html extension in urls to allow local file browsing"
echo "Antora configuration"
echo " --branch <branch-name> Name of the branch when keeping a single branch per component"
echo " --component <component-name> Name of the component when keeping a single branch per component"
echo " --component-with-branches <form> Components and branches when using 'Multiple Repositories'."
echo " Pass one argument per component. For instance, --component-with-branches bcd:3.4 --component-with-branches bonita:7.11,2021.1"
echo " --fetch-sources <boolean> 'true': fetch documentation content sources prior building the documentation. Defaults to 'false' (on CI, fetch is always done)"
echo " --force-production-navbar <boolean> 'true': use the regular navbar instead of the preview one. Defaults to 'false'"
echo " --hide-edit-page-links <boolean> 'true': hide all edit page links (useful when generating documentation archive). Defaults to 'false'"
echo " --hide-navbar-components-list <boolean> 'true': hide components list in navbar. Defaults to 'false'"
echo " --local-sources <boolean> 'true': use locally checkout sources in a working directory along the one of this project (useful to test local changes without push) , otherwise, use antora cache. Defaults to 'false'"
echo " --local-ui-bundle <boolean> 'true': use locally build ui bundle whose sources are in a working directory along the one of this project, otherwise, use antora cache. Defaults to 'false'"
echo " --pr <PR_NUMBER> Number of the Pull Request related to the preview (when apply). Used to display context information within the preview."
echo " --single-branch-per-repo <boolean> 'true': only keep the latest declared branch for each component, 'false': use all branches. Defaults to 'false'"
echo " --site-url <url> Custom Url of the site preview. If set to 'DISABLED', remove the site.url from the Antora playbook. Defaults to the original url defined in the Antora playbook."
echo " --site-title <string> Title of the site preview. Use generated title if not set."
echo " --type <string> If set to 'local', use html extension in urls to allow local file browsing"
echo " --use-all-repositories <boolean> If set to 'true', use all sources repositories and branches defined in the production Antora playbook. Defaults to 'false'"
echo " --use-multi-repositories <boolean> If set to 'true', use several repositories and branches passed with the --component-with-branches options. Defaults to 'false'"
echo " Environment configuration"
echo " --ci <boolean> 'false': assume the script is running on local dev machine and don't run some setup commands. Defaults to 'true'"
echo "Environment configuration"
echo " --ci <boolean> 'false': assume the script is running on local dev machine and don't run some setup commands. Defaults to 'true'"
echo " --only-generate-playbook If this option is pass, only generate the preview Antora playbook and skip the documentation generation"
}
......@@ -35,28 +51,29 @@ function usage() {
# Parse arguments
########################################################################################################################
runOnCI=true
extraAntoraArgs=
extraAntoraOptions=
args="$@"
scriptOptions="$@"
echo "Script Options: ${scriptOptions}"
# Help
if [[ "$args" == *"--help"* ]]; then
if [[ "$scriptOptions" == *"--help"* ]]; then
usage
exit 0
fi
# if arguments contain '--ci false', don't run 'npm ci'
if [[ "$args" != *"--ci false"* ]]; then
if [[ "$scriptOptions" != *"--ci false"* ]]; then
echo "Assume script is running on CI environment"
# force fetch, whatever the cli arguments are
extraAntoraArgs="--fetch"
# force fetch, whatever the script options are
extraAntoraOptions="--fetch"
else
echo "Assume script is NOT running on CI environment"
runOnCI=false
fi
echo "Extra Antora Arguments: ${extraAntoraArgs}"
echo "Extra Antora Options: ${extraAntoraOptions}"
########################################################################################################################
......@@ -67,9 +84,13 @@ if [[ $runOnCI == "true" ]]; then
npm ci
fi
# See the node script for the list of arguments
node scripts/generate-content-for-preview-antora-playbook.js "$@"
node scripts/generate-content-for-preview-antora-playbook.js ${scriptOptions}
if [[ "$scriptOptions" == *"--only-generate-playbook"* ]]; then
echo "Skip documentation generation"
exit 0
fi
echo "Building preview..."
rm -rf build/
./node_modules/.bin/antora --stacktrace ${extraAntoraArgs} antora-playbook-content-for-preview.yml
./node_modules/.bin/antora --stacktrace ${extraAntoraOptions} antora-playbook-content-for-preview.yml
echo "Preview built"
= Developers documentation
= How-to documentation
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
== For Documentation Content Writers
* xref:content/CONTRIBUTING.adoc[Guidelines for contributing to documentation content]
== Developers documentation
* xref:documentation-components-and-versions.adoc[Documentation Content: Component and Versions management]
* xref:architecture.adoc[Architecture Overview]
* Tips for Documentation Content Writers
** xref:documentation-versions.adoc[Documentation Content Versions]
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
* migration from the old documentation site (archives)
** xref:./migrate-from-old-documentation-site/doc-content-conversion-from-md-to-adoc.adoc[Convert markdown content to asciidoctor]
** xref:./migrate-from-old-documentation-site/migration-steps-put-the-site-live.adoc[Migration to put the site live]
......@@ -2,6 +2,8 @@
This document provides details on the architecture of the documentation site, in order to ease future developments.
image::images/DocToCloud-Architecture-BigPicture.png[]
== Chore solution: https://antora.org/[Antora]
Antora is a multi-repository documentation site generator.
......
= Contribute to the Bonita documentation content
:icons: font
:toc:
:toclevels: 4
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
We are pleased to receive any kind of contribution (issues, pull requests, suggestions ...).
== Contribution check
Before opening a pull request, please check our few recommendations:
Verify that each updated `adoc` file starts with:
[source,adoc]
----
= A short title
:description: Put just after title (without whitespace) a short description to explain what we can retrieve in this page.
You can put you content after metadata block
----
NOTE: This metadata information is useful to improve our visibility for search engine (SEO)
== Short presentation of the documentation environment
https://docs.asciidoctor.org/asciidoc/latest/[Asciidoc] is the markup language chosen to write our documentation content.
You can check the official documentation site to learn more on Asciidoc syntax.
If you know the Markdown syntax, please check the https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown[Asciidoc vs Markdown]
documentation comparison to speedup the learning.
We are using https://docs.antora.org/[Antora] to generate the Bonita documentation.
For more details about how the generation works, see the xref:../architecture.adoc[Architecture documentation] and the
xref:../README.adoc[development documentation].
== Tips for writing the documentation content
=== Media
==== Prefer source code documentation to code screenshot images
Please don't add screenshot of source code, configuration file.
This has the following issues
* maintenance: typo fixes, updates, ... can not be managed easily. Differences between documentation are harder to manage (binary merge issues)
* the source cannot copy/paste for reuse
* image content is larger than text, so this slow down the site display (especially on mobile if the image is too large) and increase the bandwith consumption
in the infrastructure (increase bill)
* the AsciiDoc code support is very easy to set up and powerful. See
* for an example of image to source example replacement, check https://github.com/bonitasoft/bonita-doc/pull/1492[Bonita 2021.1 product-versioning replacement]
==== Embed videos
It is possible to embed videos as it is done in Bonita 2021.1 index page: https://docs.asciidoctor.org/asciidoc/latest/macros/audio-and-video/
* A default/max size is set for the mobile view
* there is no default for the desktop view at the moment, so you should set the dimensions when declaring the `video` macro
as in the following example
[example]
+video::038g85tvzo4[youtube, width=640,height=380]+
==== Asciinema
https://asciinema.org/[Asciinema] provides a great way for sharing shell sessions recording, making documentation more lively !
Once you have created a `.cast` file, you can add it to your document with the following markup
.sample asciinema adoc.
[source, asciidoc]
----
== Asciinema embedded
Example of embedded asciinema recording:
++++
<asciinema-player src="_images/images/<path_to_your_cast_file>.cast" speed="2" theme="monokai" title="Example of embedded asciinema recording" cols="240" rows="32"></asciinema-player>
++++
----
The generated asciidoctor (before transformation by Antora) document should render like something like this:
[.thumb]
image::images/asciinema_sample_rendering.png[]
=== Cards
You can use card style in your page. Please don't abuse it, and try to only use it on index pages.
.Card display in after HTML generation
You can update *link*, *title* and description for each card.
To do it, you need to use this following syntax:
[source,adoc]
----
[.card-section]
== Highlight
[.card.card-index]
--
yourInternalOrExternalLink[[.card-title]#Card Title# [.card-body.card-content-overflow]#pass:q[You can write a short description here to display it in the card body.]#]
--
----
You can use many cards in same card section. +
Please keep this technical syntax to avoid error.
NOTE: If you want to see a real example, please consult the index.adoc file in https://github.com/bonitasoft/bonita-doc/blob/7.12/md/index.md[bonita documentation GitHub repository].
WARNING: If description in card body is too long (more than 3 lines), we will hide the excess.
=== Variables and attributes
You can define asciidoc attributes in the `antora.yml` file at repository root and reference it in content page.
For a detailed documentation about attributes, see the https://docs.asciidoctor.org/asciidoc/latest/attributes/attribute-entry-substitutions/[asciidoc attribute documentation].
[source,yml]
----
asciidoc:
attributes:
bonitaVersion: 2021.1
----
[example]
Use `{bonitaVersion}` syntax to reference this attribute in content. It will be replaced by `2021.1` for each occurrence.
==== Disabling attribute substitution
Any elements around braces are interpreted as attribute and so, Asciidoctor tries to substitute them. If the value around braces is not related to
a declared attributes, warnings are emitted when generating the html files. +
For instance, in `+${CATALINA_HOME}/conf/jaas.cfg+`, Asciidoctor tries by default to substitute `CATALINA_HOME` which is not something we want
as we want to document an example with bash substitution.
To disable attribute substitution in inline text, add a `+` character around the text that contains the braces
* globally around an inline code extract like `\+${CATALINA_HOME}/conf/jaas.cfg+`
* just around the braces: `$+{CATALINA_HOME}+/conf/jaas.cfg`
See https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/#inline-passthrough-macros for more details.
==== Attributes substitution in blocks
Notice that by default there is no attribute substitution in blocks, so extra configuration is needed in that case.
More details are available in https://docs.asciidoctor.org/asciidoc/latest/subs/apply-subs-to-blocks/
We recommend to use explicit macro on part of the block that requires substitution. This allows to mix the `{..}` for elements that
should not been substituted (for instance, maven properties or bash variables).
In the block, enable the macros by adding the `subs` configuration like `[source,xml,subs="+macros"]` and in the block content, set `pass:a[{...}]` around
the attribute you want to substitute. For instance, `<bonita.version>pass:a[{bonitaVersion}].0</bonita.version>`. +
This configuration then let parts like `<version>${bonita.version}</version>` not substituted.
It is also possible to configure substitution globally for the block (see the documentation).
=== Admonitions
What are Admonitions: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions
==== GitHub may not render admonitions
See this https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/#using-emoji-for-admonition-icons[asciidoc documentation] for more details.
==== Custom admonition for Cloud
see https://github.com/bonitasoft/bonita-documentation-theme/pull/53
=== Antora modules
You can use Antora modules to clarify content (for instance, getting-started guides, how-to articles). +
See https://docs.antora.org/antora/2.3/module-directories/#module.
[quote]
____
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 folder): easier to identify what pages and images
are related to "getting started", easier maintenance, ....
____
=== Alias when renaming pages
IMPORTANT: Impact on SEO
See https://docs.antora.org/antora/2.3/page/page-aliases. +
Successfully experimented in https://github.com/bonitasoft/bonita-ici-doc#123