Centralize, update, improve CBI documentation

[fredg02]

Based on https://bugs.eclipse.org/bugs/show_bug.cgi?id=480844, we should find a good location (not necessarily this repo) and collect all the info about CBI.

[fredg02]

See also https://bugs.eclipse.org/bugs/show_bug.cgi?id=513252

[heurtematte]

I see several points to discuss regarding CBI documentation:

1- Workflow

I propose using a documentation-as-code approach to take advantage of Git's concepts for validation and information sharing within the team with PR, reviews, ...

2- Writing (the format)

Different formats are available for document-as-code approach, such as Markdown or ASCIIDOC. No particular preference; both can be used depending on the context and type of documentation.

3- Organization

Documentation should be as close to the code as possible. It should be directly present in the project's code repository, either in the root directory or in a '/docs' directory.

4- Publishing

Publishing through a static website that aggregates the documentation from various projects present in versioned code repositories. See Antora: https://antora.org/"

I hope this helps as a starting point to restructure CBI documentation!

[heurtematte]

@fredg02 a quick POC with Antora and mkdocs to show how docs-as-code approach can be articulated. This involved configuration, aggregating repository documents and publishing to a static website with a CI.

NOTE: Antora has fewer docs integrated due to project conversion.

Antora

source: https://gitlab.com/sebastien.heurtematte1/eclipse-cbi-antora website: https://eclipse-cbi-antora-sebastien-heurtematte1-e89513092fa79467be20c.gitlab.io/eclipse-cbi-antora/1.0.0/index.html

Pros:

• multi repo is native
• Manage multiple version
• Default layout is moderm and easily extensible
• Website module/page organization
• CI integration easy

Cons:

• Only asciidoc, not markdown (maybe with a pandoc preprocessing)
• Project must have a antora.yml file configuration, and have a specific doc organization

Mkdocs with mkdocs-multirepo-plugin

source: https://github.com/heurtematte/eclipse-cbi-mkdocs website: https://heurtematte.github.io/eclipse-cbi-mkdocs/

Pros:

• Integration markdown and asciidoc
• Easy configuration, only one file! mkdocs.yml

Cons:

• Module organization is in the header, not so easily extensible
• Manage one branch per repo
• CI integration not compatible with every tool, docker integration failed, and gitlab-ci integration failed too. Only local and github action works.