Writting documentation

General guidelines

• Any documentation written for this project must be in the Markdown format.

• Documents can include references to local images.

• Preferred format for diagrams is embedded Mermaid blocks, like:

  ```mermaid
    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
  ```
  

• Primary information must be located in the README.md file of each module. Additional documents can be created for further details when necessary.

• Any document should be provided in English as primary language, and Spanish as secondary language. Spanish versions would be named adding the suffix es before the file extension (for example, README_es.md).

• To the extent possible, documents have to be readable both in the documentation site and in the Github viewer.

Documentation site generation

The documentation site is build from the source documents located in the main branch, but the actual site lives in the docs branch that it is published as the URL https://iti-ict.github.io/kukumo/ . This branch has no code and it should not be manually altered in normal circumstances.

The tool used to generate the HTML is Docsite Maven Plugin (check the link for how it works in detail). It is automatically generated each time a commit is pushed, as a part of the build process.

Manual site generation

The preferred way to deploy the documentation site is relay on the build script, but it is possible to do a manual push onto the docs branch.

The generation process has two stages:

1. Generate automatic documentation for each module

By applying the Maven goal docsite:generate, a site would be automatically generated in the target/docsite folder of each module. They are created from the README.md files along with any other documentation previously generated (such as Javadoc, Surefire test reports, etc.). In additions, extra configuration is provided in the pom.xml file at the root folder of the project, that is inherited to each module.

2. Generate the overall documentation site

By applying the Maven goal docsite:aggregate after the former step is done, the actual documentation site for the entire project would be generated. In this case, instead of relying on the auto-detecting capabilities of the plugin, the site structure is explicitly defined in the docsite.json file. Here, we defined the main page as well as the main navigable sections. The module-local sites generated previously are copied to the final site.