La qualité, c'est un tout

Il y a peu nous expliquions les actions prises et envisagées pour améliorer la qualité de Lizmap. Il en va de même pour la documentation des logiciels ou des extensions que nous produisons. La documentation fait partie de la qualité.

Lizmap

La documentation utilisateurs concernant Lizmap Web CLient souffre un peu de notre manque de temps. Néanmoins, nous avons décidé de l'améliorer.

Nous avons par exemple décidé de ne plus accepter de nouvelles fonctionnalités dans Lizmap si celles-ci ne viennent pas avec un brin de documentation (du texte et des captures d'écran).

La documentation Lizmap, disponible sur GitHub 3liz/lizmap-documentation, utilise Sphinx, et est traduisible sur Transifex dans plusieurs langues. La documentation format HTML est disponible sur https://docs.lizmap.com

Concernant la documentation du code, nous avons également un pull request en cours pour la génération avec PhpDoc et nous sommes aussi en train d'améliorer les annotations et docstrings au sein du code PHP. Cela nous permettra d'accentuer le travail sur les DocStrings, c'est-à-dire la documentation du code, des classes et des fonctions.

Autres produits

Parallèlement à Lizmap Web Client, nous misons aussi sur la documentation des extensions et des modules que nous développons. Nous publions l'ensemble de la documentation de nos projets open-source sur https://docs.3liz.org.

Pour cela, nous utilisons MkDocs avec le thème Material. Pour chaque extension QGIS ou pour chaque module Lizmap, nous ajoutons un site dédié grâce à MkDocs et nous le référençons sur https://docs.3liz.org.

MkDocs nous permet de rédiger le manuel utilisateur de manière simple et ergonomique au format Markdown. L'utilisation de ce format Markdown reste très accessible à tous, sans avoir à apprendre une syntaxe particulièrement difficile.

Additionnellement, il existe de nombreuses extensions au Markdown, comme Mermaid qui permet de faire des diagrammes (classes, cas d'utilisations, scénario, etc.), Admonitions pour insérer des boîtes de texte graphique, etc.

Pour la documentation d'une base de données PostgreSQL, nous utilisons SchemaSpy qui permet la génération d'un site HTML avec l'ensemble des tables, des champs, des fonctions SQL. Il peut même présenter quelques anomalies possibles. L'ensemble de cette génération de documentation est automatisé sur la CI GitLab et/ou GitHub.

Si le projet en question, n'utilise pas une base de données PostgreSQL, mais un GeoPackage avec des tables et des relations, nous utilisons une solution maison qui lit les fichiers CSV de définition des tables ainsi que les relations du projet QGIS et génère un Markdown contenant le diagramme des classes selon la nomenclature Mermaid. Nous obtenons ainsi une représentation graphique du diagramme de classe pour les tables du fichier Geopackage.

Concernant les extensions QGIS, nous utilisons dans la plupart des cas le framework Processing qui permet de fournir des algorithmes de traitements dans nos extensions. Avec l'aide d'un script Python, nous générons automatiquement une page en Markdown de chaque algorithme avec la capture d'écran associé (grâce à l'API Qt). Dans QGIS 2, dans le framework Processing, nous pouvions définir des infobulles pour les paramètres d'un algorithme. Malheureusement, suite au refactoring QGIS 3, cette possibilité avait été perdue. Nous avons rajouté cette possibilité depuis QGIS 3.14 pour améliorer la documentation de nos algorithmes. Ces infobulles sont également présentes dans l'export Markdown.

Exemples

Pour illustrer l'ensemble de ces éléments, prenons exemple sur l'extension PgMetadata, extension QGIS pour avoir des métadonnées sur des couches PostgreSQL :

• La documentation se situe sur https://docs.3liz.org/qgis-pgmetadata-plugin/ On y trouve la présentation du projet, le manuel utilisateur, les références…
• La documentation Processing est automatiquement générée à partir du code Python (tableau et capture d'écran).
• La documentation de la base de données est engendrée automatiquement à partir des fichiers SQL dans le code source.

Concernant la génération des diagrammes avec Mermaid, présentons le cas de l'extension QGIS Mercicor avec son diagramme cliquable ou alors son modèle de données générés à partir du code CSV (ainsi que les tableaux).

Pour la mise à disposition des extensions QGIS, nous utilisons QGIS-Plugin-CI. Cela permet de mettre à disposition un dépôt d'extension QGIS pour une extension, protégé ou non par login/mot de passe. MkDocs nous permet encore de mettre à disposition le tutoriel pour l'installation du dépôt dans QGIS.

En cours

Concernant la documentation, nous avons d'autres pistes que nous allons commencer à explorer :

• génération automatique d'un fichier Markdown concernant les Actions QGIS dans une extension QGIS afin de décrire les interactions possibles avec l'utilisateur.
• Améliorer le respect de la norme Python PEP 257 pour l'écriture des DocStrings
• Améliorer le respect de la norme Python PEP 3107 pour l'écriture des Annotations Python
• Générer la documentation du code avec l'aide de ces deux PEP précédentes

Notre effort est récent, nous n'avons pas encore adapté les documentations de tous nos projets à cette nouvelle manière de travailler, mais nous le faisons au fur et à mesure du temps que nous pouvons dédier au projet.

De même nous avons de la dette documentaire. C’est-à-dire de la documentation qui n'est pas à jour, de la documentation incomplète, de la documentation sans illustration. Nous allons petit à petit combler ces lacunes. En tant qu'utilisateurs de nos logiciels, vous pouvez nous aider de deux manières :

• la première, c'est en ajoutant des copies d'écran (en anglais de préférence), de prendre en main l'outil MkDocs et de nous proposer un patch de mise à jour de la documentation
• la deuxième est de contacter notre gérant et lui demander un devis pour que nous puissions consacrer du temps à écrire et mettre à jour de la documentation.

Etienne Trimaille et Ludovic Hirlimann