feat(bici): generate BICI documentation (#17)

Integrate the BICI migrated content and document how this has been done for reuse with other content (based on previous poc).
The antora-ui bundle has been generated from a previous poc, it will be updated with content of bonitasoft/bonita-documentation-theme later

This also setup
    - build with npm: shared commands and shared dev/build setup
    - antora playbook: more ready for GH pages deployment
    - allow to build the site for local and production usage
    - allow to run local http server for evaluation

.gitignore

-build/*
+build/
+.idea/
+node_modules/
+.cache/
+*.DS_Store

README.adoc

+= New Bonita Documentation Site
+// External URIs:
+:url-antora: https://antora.org
+:url-asciidoctor: https://asciidoctor.org/
+:url-node: https://nodejs.org
+:url-nvm: https://github.com/creationix/nvm
+:url-nvm-install: {url-nvm}#installation
+
+
+*_DISCLAIMER: this is a work in progress._*
+
+
+== Architecture
+
+Static site generation based on {url-antora}[Antora] using {url-asciidoctor}:[Asciidoctor] documentation content stored in various Git repositories.
+
+
+== Build
+
+=== Requirements
+
+
+{url-node}[Node 12.x] (may work with newer versions, no guarantee). For more details, see the  https://docs.antora.org/antora/2.3/install-and-run-quickstart/[Antora installation guide].
+
+While you can install Node from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to install and manage Node.
+Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.
+
+NOTE: all npm commands are intended to be run from the repository root folder.
+
+=== Build the static site for production
+
+Run
+```bash
+npm install
+npm run build
+```
+The static site is then available in the `build/site` folder.
+
+
+=== Local development
+
+The `antora` CLI is available by calling `./node_modules/.bin/antora --version`
+
+For more CLI options, see https://docs.antora.org/antora/2.3/cli/options/
+
+
+==== Building for local developments
+
+For a site that can be load from local disk
+```bash
+npm run local:build-static
+```
+
+For a site to be served by the development <<http server>>
+```bash
+npm run local:build
+```
+
+
+==== 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, ....).
+
+You can rebuild the site while the server is running, updated files are directly considered by the server (no cache).
+
+
+== Documentation
+
+See the xref:./docs/README[dedicated folder].

Readme.adoc

-=== Coming soon
\ No newline at end of file

bonitasoft.github.io.yml

 site:
-  title: Bonita documentation 2.0
-  url: http://localhost:8080/documentation
-  start_page: bonita::index.adoc
+  title: Bonita Documentation
+  # features that depend on the site URL: https://docs.antora.org/antora/2.3/playbook/site-url/#when-should-the-site-url-be-set
+  # when building for local usage, this is overridden.
+  url: https://bonitasoft.github.io/
+  start_page: bici::index.adoc
+
+# see https://docs.antora.org/antora/2.3/playbook/configure-runtime/
+runtime:
+  cache_dir: ./.cache/antora
+
 content:
   sources:
-    - url: https://github.com/alachambre/antora-sources-test.git
-      branches: [master, 7.11]
-    - url: git@github.com:alachambre/antora-source-api.git
-    - url: https://github.com/alachambre/antora-sources-test-2.git
+#    - url: https://github.com/alachambre/antora-sources-test.git
+#      branches: [master, 7.11]
+#    - url: git@github.com:alachambre/antora-source-api.git
+#    - url: https://github.com/alachambre/antora-sources-test-2.git
+
+    # local development: use ../bonita-ici-doc (see also https://docs.antora.org/antora/2.3/playbook/author-mode/)
+    - url: https://github.com/bonitasoft/bonita-ici-doc.git
+      branches: [master]
+
 ui:
   bundle:
-    url: ../antora-ui/build/ui-bundle.zip
+    url: ./resources/antora-ui-bundle.zip
 asciidoc:
   extensions:
   - ./lib/source-url-include-processor.js

docs/README.adoc

+TODO
\ No newline at end of file

docs/migrating-content-markdown-to-asciidoctor.adoc

+= Migration tips: from markdown to asciidoctor
+
+Note: current work used to migrate the BICI documentation, see https://github.com/bonitasoft/bonita-ici-doc/pull/118[PR #118]
+
+== Markdown to Asciidoctor generation
+
+=== Tool installation
+
+TIP: Proposed tool Kramdoc aka https://github.com/asciidoctor/kramdown-asciidoc:[kramdown-asciidoc]. See also this https://matthewsetter.com/technical-documentation/asciidoc/convert-markdown-to-asciidoc-with-kramdoc/:[article].
+
+
+* Require Ruby
+* gem install kramdown-asciidoc, see the https://kramdown.gettalong.org/installation.html:[installation guide] for more details
+* installation check: `kramdoc --version`
+
+*TODO*: docker ruby image with gem installed to avoid polluting our machines?
+
+=== Migrate sources
+
+Sources (markdown and images files) are stored in the `md` folder of the documentation content repository.
+
+[WARNING]
+====
+index and releases-notes pages generally contain html elements that cannot be automatically migrated. +
+There is also a dependency on font-awesome css (`fa-` directives). Font awesome support is available in asciidoctor
+
+* 1st comment the html part
+* Run the migration
+* In the migrated content, manually migrate the html
+====
+
+
+Run the following command to generate the converted files:
+[source,bash]
+----
+find ./ -name "*.md" \
+       -type f | xargs -I @@ \
+       bash -c 'kramdoc \
+               --format=GFM \
+               --output=@@.adoc @@';
+----
+
+WARNING: test with additional `--wrap=ventilate` option
+
+
+== Cleanup
+
+Migrate custom Bonita tags for notes, warnings, ....
+
+For instance, `:::info Note: for Enterprise, Performance and Efficiency editions only.:::` to
+`NOTE: Note: for Enterprise, Performance and Efficiency editions only.`
+
+
+Note:
+[source,bash]
+----
+sed -i 's/::: info/NOTE:/g' *.adoc
+sed -i 's/:::info/NOTE:/g' *.adoc
+sed -i 's/::: warning/WARNING:/g' *.adoc
+sed -i 's/:::warning/WARNING:/g' *.adoc
+sed -i 's/::://g' *.adoc
+----
+
+NOTE: for macOS add `''` after the -i option.
+
+
+
+== rename files
+
+[source,bash]
+----
+for f in *.md.adoc; do mv -- "$f" "${f%.md.adoc}.adoc"; done
+# Remove remaining md files
+rm -rf *.md
+----
+
+== move file to the right folder
+
+* Antora layout: move the `md` folder to `modules/ROOT/pages`
+* taxonomy: move the page to `modules/ROOT/pages`, otherwise it is considered as a regular pages
+* others
+
+== images management
+
+CAUTION: in progress, a definitive solution must be found
+
+[WARNING]
+====
+Antora expects (at least by default) that images are stored in the `modules/ROOT/assets/images` folder, then they are available
+directly in pages as link without having to add relative path. In the generated site, they are then stored in the `_/_images` folder.
+
+In the original markdown content, the images are accessed through the `images` relative folder. So, if the page content
+is not changed, the images must be stored in
+====
+
+*_Draft_*

generate.sh

-rm -rf build
-antora --fetch antora-playbook.yml --stacktrace

package.json

+{
+  "name": "bonita-documentation-site",
+  "version": "0.0.1",
+  "scripts": {
+    "clean": "rimraf build .cache",
+    "build": "antora --stacktrace --fetch --clean bonitasoft.github.io.yml",
+    "local:build-static": "antora --stacktrace --fetch --html-url-extension-style default bonitasoft.github.io.yml",
+    "local:build": "antora --stacktrace --fetch --url http://localhost:8080 bonitasoft.github.io.yml",
+    "serve": "http-server build/site -c-1 --port 8080"
+  },
+  "devDependencies": {
+    "@antora/cli": "^2.3.4",
+    "@antora/site-generator-default": "^2.3.4",
+    "http-server": "^0.12.3",
+    "rimraf": "^3.0.2"
+  }
+}