Unverified Commit b73ff825 authored by Adrien's avatar Adrien Committed by GitHub
Browse files

doc: introduce architecture documentation (#160)

parent 8071bd82
......@@ -14,6 +14,8 @@ endif::[]
: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]
*_DISCLAIMER: this is a work in progress._*
......@@ -22,6 +24,8 @@ endif::[]
Static site generation based on {url-antora}[Antora] using {url-asciidoctor}:[Asciidoctor] documentation content stored in various Git repositories.
More details are available in the xref:docs/architecture.adoc[Architecture Documentation].
== Build
= Developers documentation
* migration from the old documentation site
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
* xref:architecture.adoc[Architecture Overview]
* Tips for Documentation Content Writers
** xref:documentation-versions.adoc[Documentation Content Versions]
* 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]
* xref:configure-netlify-redirects.adoc[Configure netlify redirects]
= Documentation Site architecture
This document provides details on the architecture of the documentation site, in order to ease future developments.
== Chore solution: https://antora.org/[Antora]
Antora is a multi-repository documentation site generator.
The Antora playbook is configured by the file _antora-playbook.yml_. +
This configuration file lists all the components, and the branches to build. It also references the UI bundle and some additional Asciidoctor extensions, both used to generate the HTML.
The Antora generator retrieves Asciidoctor sources from our documentation content repositories, and then generate a static HTML website from those sources.
A GitHub workflow is available to generate this static documentation (useful for oldest version not host on this documentation site).
== UI Bundle
The UI bundle source repository can be found here: https://github.com/bonitasoft/bonita-documentation-theme[bonita-documentation-theme].
The UI Bundle architecture is detailed on the UI bundle Readme.
== Search solution: Algolia
Because of our open source status, https://docsearch.algolia.com/[DocSearch by Algolia] offers us freely a search solution (Thanks a lot to them! ❤️). +
The configuration file can be found https://github.com/algolia/docsearch-configs/blob/master/configs/bonitasoft.json[here].
This file indicates to the DocSearch crawler the pages to crawl, and the elements to index.
== Host solution: Netlify
The documentation is hosted on https://app.netlify.com/sites/documentation-bonita[Netlify].
Netlify allow us to manage redirection with the `netlify.toml` file at root of this repository.
== Preview with Surge
https://surge.sh/[Surge] let us deploy previews for the
* theme development
* site development
* documentation preview when updating the content with Pull Requests
= Documentation Versions
:icons: font
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
CAUTION: this is a work in progress
NOTE: the following mainly applies to the Bonita Platform documentation part
== Bonita versions that are documented
For Bonita, the rule is the following one: +
We document the 4 currently supported Bonita versions, and **the 4 versions before**. +
== Impact on Algolia DocSearch
Each time a new version of a documented Bonitasoft project is released, this DocSearch configuration file has to be updated:
- The latest version has to be added to the projects to index
- The oldest version should be removed from the projects to index
-> It means that the DocSearch conf file should reflect this behavior.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment