Open your GIS

About documentation

Fri 07 May 2021

fr, en

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.


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.

Mermaid and Admonitions

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.



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

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 :

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:

Etienne Trimaille and Ludovic Hirlimann