Built by Maven

Use maven-site-plugin to handle documentation

Developers have to write documentation for various aims (architecture, decision, usages, configuration description).

A tool must be chosen to generate the documentation. The tool must not too much complex to install, maintain and use on developer computer and CI (Jenkins, GitLab CI). The tool must handle Markdown as this syntax is already used in various parts of AgroClim softwares. The tool must handle some other text formats to draw diagrams (eg.: PlantUML).

Considered Alternatives

Decision Outcome

  • Chosen Alternative: maven-site-plugin
  • This plugin is already used (eg.: SIDO), handles Markdown and PlantUML and is already included in the build chain.
  • According to the few requirements, the rendering is enough.
  • The configuration of pom.xml is a bit verbose.
  • By default, the layout is a bit dated and does not offer searching feature.

Pros and Cons of the Alternatives

Docusaurus 2.0

  • + by default, the rendered documentation is clear
  • + supports Markdown
  • - needs npm and one command
  • - needs a lot of files for configuration

mdBook

  • + needs a simple downloadable binary
  • + only one file for configuration
  • + supports Markdown
  • - all pages must be present in the menu (SUMMARY.md), so it is too long

MkDocs

  • + by default, the rendered documentation is clear
  • + only one file for configuration
  • + supports Markdown
  • - needs python3, pip3 and one command

Pandoc

  • + exists as .deb package
  • + supports Markdown
  • - only one rendered file per command (so 1 HTML or 1 PDF)

Sphinx

  • + exists as .deb package
  • +/- supports Markdown, but documentation is for reStructuredText
  • - needs a lot of files for configuration