Aller au contenu

Documentation et livraisons

Le site de documentation

Le site est construit par Zensical à partir de docs/, une configuration par langue :

  • zensical.fr.toml : docs/fr/ (guide utilisateur + référence interne) → public/fr/ ;
  • zensical.en.toml : docs/en/ (guide utilisateur seulement) → public/en/.

tools/make_docs.sh construit les deux langues en --strict (un lien cassé fait échouer la construction) et écrit public/index.html, qui renvoie vers l'anglais. Les images n'existent qu'une fois, dans docs/fr/images/ : le script en fait une copie dans docs/en/images/ (ignorée par git).

pip install zensical
.\tools\make_docs.cmd              # construction, comme la CI
.\tools\make_docs.cmd serve fr     # aperçu local sur http://localhost:8000

Règles

  • Toute nouvelle page de docs/fr/ s'ajoute au nav de zensical.fr.toml.
  • Une page du guide utilisateur (docs/fr/index.md, docs/fr/guide/) se traduit dans docs/en/ au même chemin (le sélecteur de langue en dépend) et s'ajoute au nav de zensical.en.toml. La référence interne n'est pas traduite.
  • Les paramètres des blocs sont documentés dans guide/blocs.md : les tenir à jour dans les deux langues quand un paramètre change.
  • Un lien vers un fichier du dépôt hors de docs/ s'écrit en URL GitLab absolue (https://gitlab.com/bdelaup/modelica_statecharts/-/blob/main/...).

Publication

.gitlab-ci.yml n'a qu'un job, pages : à chaque push sur main, le runner partagé de GitLab installe Zensical, lance tools/make_docs.sh et publie public/ sur GitLab Pages : https://bdelaup.gitlab.io/modelica_statecharts/.

Les versions

Une version est un tag vX.Y.Z posé à la main ; versions 0.x tant que l'API n'est pas déclarée stable. Aucune archive n'est construite : les utilisateurs téléchargent le dépôt au tag (cf. Installation).

  1. Mettre à jour requirements.md, CLAUDE.md et la documentation.
  2. .\tools\run_tests.cmd --copy : tout doit être PASS.
  3. Committer, puis git tag -a vX.Y.Z -m "..." et git push --follow-tags.