Quality everywhere

We recently explained that our plan of actions was to upgrade the quality with Lizmap releases. We are having a similar effort for the documentation of all the software and plugins that we are writing. Documentation is part of the quality process.

Lizmap

User documentation for Lizmap Web Client suffers from our lack of time. Realizing that, we decided to work on making it better.

First step is to refuse new features in Lizmap, if they are not bundled with some documentation (some text and some screenshots).

Lizmap's documentation is built with sphinx and is pushed to transifex for translations. We host an HTML version of it at https://docs.lizmap.com, and it's available in several languages.

We are also working on documenting our code source in better ways. There's a pull request to use PhpDoc. We are slowly adding more comments and docstrings to our PHP code. This effort will let us document our code, classes, and functions using DocStrings.

Other products

Our effort is global, it will touch everything we produce. We host all the documentation for all our open-source projects at https://docs.3liz.org.

For these, we use MkDocs with the Material Theme. For every QGIS plugins and for each Lizmap module, we create a specific website with MkDocs and link to it from https://docs.3liz.org.

We've chosen MkDocs , because it's easy to create a user manual in Markdown, with that tool. Markdown is very easy to grasp and makes it easy to write the documentation. In addition, Markdown is extensible with tools like Mermaid to make diagrams or Admonitions to insert graphics and text.

When documenting things related to PostgreSQL, we use SchemaSpy. It generates a website with tables, fields, and SQL functions. This is automated in either GitLab or GitHub depending on the status of the project (public).

If a project doesn't use PostgreSQL, but for instance a Geopackage with tables and relations, we are using a home brew solution. The given solution reads CSV files and relations from the QGIS project file. Then it generates a Markdown containing: class diagrams, relations, tables which will be parsed by Mermaid.

For QGIS plugins, we use the Processing framework to provide algorithms to QGIS. With the help of a python script, we generate the Markdown for each algorithm and associated screenshots (using the Qt API). When using a version of QGIS > 3.14, tooltips present in the UI are also present in the generated markdown documentation.

Examples

Let's see how it works with our PgMetadata QGIS plugin, that lets you see PostgreSQL metadata from QGIS:

• Documentation is at https://docs.3liz.org/qgis-pgmetadata-plugin/. We present the project and you'll find the user manual, references…
• The processing documentation is completely generated through some python scripts (tables and screenshots).
• The database documentation is built using the SQL source code.

For diagrams made with Mermaid, we can use the Mercicor QGIS plugin example with its clickable workflow diagram and its data model generated from the CSV code (and tables below).

For delivering QGIS plugins, we use QGIS-Plugin-CI. This allows us to make a QGIS Plugin repository per plugin, protected or not by login/password. MkDocs allows us to have the tutorial how to install a custom QGIS repository.

Work in Progress

On top of what we already do, we are exploring the following ideas :

• Markdown generation for QGIS Actions so interactions with users can be documented.
• Stricter use of Python PEP 257 for writing DocStrings.
• Stricter use of Python PEP 3107 for Python annotations.
• Generate code documentation based on the PEP above.

We've only recently started working on making our documentation top-class. All our projects haven't switch yet to this new process, we do it one at a time depending on the time we can dedicate to the project.

We are aware that we have a documentation debt: some are obsolete, some are incomplete, some lacks screenshots. We are slowly working on fixing all of these. As a user you can help in some ways:

• You can make a missing screenshot (in English please), learn how to use MkDocs, and propose documentation patches.
• Contact our manager and ask to fund some documentation work.

Etienne Trimaille and Ludovic Hirlimann