Contribute to documentation

The documentation of this project is located into the docs/ folder.

Create a new Documentation page

Write a new page

To write a new page of documentation, create a new file inside the docs/modules/ROOT/pages subfolder, with the .adoc extension. You should then write your content using Asciidoc language.

Use the AsciiDoc Syntax Quick Reference and the Asciidoc Cheatsheet

Convert an existing Markdown document

Alternatively, if you have an existing Markdown document, you can convert it using the pandoc tool.

Pandoc call to convert Markdown into Asciidoc, preserving format.

pandoc -f markdown -t asciidoc --wrap=preserve --shift-heading-level-by=-1 --standalone --output=FILENAME.adoc FILENAME.md

Include the new page

To include your page in the resulting website, edit the docs/modules/ROOT/nav.adoc file to add an index entry under the right section.

* Section
** xref:module_name:my_documentation_under_Section.adoc[My documentation's title]

Customize the appearance

The UI of the documentation is built in an external project named Antora-ui for Camptocamp.

First make sure to follow the development quickstart, then clone and initialize the UI Project.

For detailled information on the way to customize the UI, please refer to the corresponding documentation here.

Viewing your changes locally

You can generate the doc using the docker image of antora and put it in a local directory. For example with the following:

docker run --rm -it --user $(id -u)  -v $LOCAL_ABSOLUTE_PATH/camptocamp-devops-stack:/tmp/docs docker.io/antora/antora:2.3.4 generate /tmp/docs/antora-playbook.yml  --to-dir /tmp/docs/docs/output --cache-dir=./.cache

Then to visualize your result you can open your browser to the file $LOCAL_ABSOLUTE_PATH/camptocamp-devops-stack/docs/output/index.html and browse your doc.