Documenter tricoteuses pour les développeurs & développeuses

Bonjour,

Je voudrais documenter tricoteuses, au moins la partie sur laquelle @eraviart a travaillé c’est à dire récupérer l’open data disponible, l’historiser sous git dans https://framagit.org/tricoteuses/open-data-assemblee-nationale.

  • Sur un nouveau dépot https://git.en-root.org/tricoteuses/developer-documentation
  • En Markdown
  • Publié sur readthedocs.org
  • Pour une audience de développeurs & développeuses qui souhaitent comprendre le format des données, leur signification et leur provenance
  • En Anglais. Parce que les développeurs & développeuses sont nécessairement anglophones. Et que des personnes souhaitant moissonner des donnés sur la fabrique de la loi au niveau global ont besoin d’une documentation en anglais.

Qu’en dites vous ?

2 « J'aime »

Après discussion ce midi, ce serait mieux d’activer le service pages de https://git.en-root.org/ sous le nom de domaine https://io.en-root.org/ (par exemple).

Le dépot https://git.en-root.org/tricoteuses/data-site servirait à alimenter https://data-site.io.en-root.org/ qui aurait un CNAME https://data.tricoteuses.fr/. Il faudrait:

Les GitLab Pages nécessitent un top level domain.

Parmi les noms de domaine à moins de 10 € / an, je vous propose :

0 votant

2 « J'aime »

J’ai donc acheté le domaine en-root.fr, pour le prix annuel de 7,19 € TTC

1 « J'aime »

mais je voulais en-root.ninja !!

… ou en-root.art… :’( :))

1 « J'aime »

Achète-les alors et on les utilisera :tongue:

1 « J'aime »

Les données publiées à https://framagit.org/tricoteuses/open-data-assemblee-nationale sont le plus proche possible des données provenant de l’assemblée nationale. Ça évite d’avoir repenser entièrement la structure des données. Les modifications sont apportées pour:

Certaines données sont ignorées, lorsqu’elles sont redondantes. Par exemple AMO10_deputes_actifs_mandats_actifs_organes_XV.json est un sous ensemble de AMO30_tous_acteurs_tous_mandats_tous_organes_historique.json.

Lorsque des modifications non backward compatibles sont apportées, elles sont rendues backward compatible. Par exemple si le nom des fichiers change, comme c’est arrivé lorsque acteurs et organes ont été publiées sous la forme d’un fichier par organe ou acteur au lieu d’un unique fichier les agrégeant.

La documentation portera sur ces données transformées.

1 « J'aime »

Pour la conversion de schema JSON en Markdown (ou plus généralement pour convertir en documentation), json-schema.org ne propose rien.

Il y a jsonschema2md mais une première tentative tombe sur un bug de 2018 toujours pas corrigé. Les annotations descriptions et title sont parfois ignorées sans qu’il soit facile de déterminer pourquoi. Et le fichier Markdown résultant n’est pas très lisible. En conclusion ce n’est pas un bon candidat.

Il y a wetzel dont l’output semble bien mais qui ne supporte pas les références relatives $ref.

Le module sphinx semble plus fonctionnel mais ne peut être utilisé que pour RST, donc ce n’est pas une option.

Plutôt que forcer, voir écrire un petit script de conversion, une option serait d’inclure le schema JSON dans la documentation. C’est un peu verbeux mais probablement assez lisible, si les descriptions sont bien indentées.

Un début de site web pour la publication des data Tricoteuses en provenance de Tricoteuses / data-site · GitLab

C’est ce qui avait été proposé structurellement. Il n’y a aucune cohérence visuellement entre Tricoteuses et Introduction — Données de Tricoteuses 1.0.0 documentation et encore moins avec https://tricoteuses.fr.

Avant de changer l’esthetique je pense qu’il faudrait:

  • Ajouter les schemas JSON
  • Ecrire de la documentation

Et faire un peu de user research pour voir comment l’audience (c’est à dire les développeurs & développeuses) arrive a s’en débrouiller. Il y a des chances pour qu’on découvre qu’il faudrait faire différement et ce serait dommage d’avoir décoré un site qu’on va détruire ou beaucoup changer :wink:

si on me gribouille des schémas vite-fait mal fait, j’peux tenter de les mettre au propre sur un logiciel de dessin vectoriel ou de diagrammes - mais attention, j’y connais rien ! :slight_smile:

1 « J'aime »

Il y a peut-être un malentendu sur la notion de “schema” dans l’expression “JSON Schema”. Les JSON schemas ne sont pas des dessins mais des (meta-)données au format JSON.

1 « J'aime »

Ce n’est pas un bon choix pour écrire de la documentation. Pas seulement parce qu’il n’y a rien pour présenter un schema JSON dans la documentation. Mais aussi parce qu’il n’est pas possible d’inclure des fichiers dans une documentation. Sauf à faire un script. RST + sphinx serait plus pratique.

Le plugin sphinx pour JSON schema fonctionne un peu mais:

Il vaut donc mieux se contenter d’inclure les JSON schema en attendant de trouver mieux.

Après avoir exploré W3C: Data on the Web Best Practices on peut dire que le gros du travail consiste à documenter les métadonnées structurelles, c’est à dire les champs de chaque fichier contenant un jeu de données.

Ca nous avance pas plus que ça :grin: Mais ça place ce qu’on fait dans un cadre. Et ça donne aussi un texte qui explique qu’une documentation des meta données structurelles aide à la compréhension du jeu de donnée. C’est de l’enfonçage de :door: ouverte mais… dans le cas improbable ou une personne prétend que l’effort est inutile, ça peut servir.