Tutorial: Modifier_la_documentation

Modifier_la_documentation

# Généralités

La documentation est générée à l'aide de jsdoc en utilisant le thème docdash.

Pour générer la documentation, il suffit de lancer pnpm run build:doc dans un terminal.

Et pour la visualiser, il suffit de lancer pnpm run doc:show dans un terminal.

Vous pouvez faire les deux actions en une ligne en lançant pnpm run doc show (sans les deux points).

# Arborescence : où sont les fichiers ?

La page d'accueil de la documentation est générée à partir du fichier src/demarrage.md.

Les différents tutoriels sont dans le dossier jsdoc/tutorials/.

Pour créer un nouveau tutoriel, il suffit de créer un fichier MarkDown (.md) dans le dossier jsdoc/tutorials/. (ien vers une "anti-sèche" MarkDown en anglais).

Les fichiers et dossiers à l'intérieur de jsdoc/static/ sont copiés tels quels à la racine du dossier de documentation lorsque celle-ci est générée. Cela permet d'avoir des fichiers et des adresses statiques qui ne passent pas à la moulinette comme le reste. L'intérêt principal étant de disposer d'un dossier d'images utilisables par la documentation.

# Créer un lien interne à la documentation

Pour créer un lien interne à la documentation, on distingue deux cas :

  • Si on veut créer un lien vers un tutoriel présent dans le dossier jsdoc/tutorials, le lien est https://coopmaths.fr/documentation/tutorial-Nom_du_fichier_MarkDown.html. Notez bien que le .md présent dans les sources est remplacé par un .html
  • Le dossier jsdoc/static/ correspond au dossier racine de la doc générée et l'intérieur de ce dossier est recopié tel quel donc pour créer un lien vers jsdoc/static/img/image.png, le lien à utiliser est tout simplement img/image.png.

# Bonus : comment est générée le reste de la documentation ?

Lorsqu'on lance pnpm run buid:doc, les fichiers base.json, mathalea2d.json, mathaleaInstrumEnPoche.json et tout.json du dossier jsdoc/ sont lus.

  • base.json va générer une documentation dans le dossier documentation/
    • dont la page d'accueil sera une version html de src/demarrage.md ;
    • qui contiendra des versions html des .md de jsdoc/tutorials/ ;
    • qui recopiera le contenu de jsdoc/static/ à la racine du dossier documentation/ ;
    • qui créera des pages html à partir des commentaires trouvés dans les fichiers src/js/modules/outils.js,src/js/modules/fractions.js,src/js/modules/Fraction.js et src/js/modules/ListeFraction.js encore une fois dans le dossier documentation.
  • mathalea2d.json va générer une documentation dans le dossier documentation/2d/ à partir des commentaires du fichier src/js/modules/2d.js et dont la page d'accueil sera créée à partir de jsdoc/2d.md.
  • mathaleaInstrumEnPoche.json va générer une documentation dans le dossier documentation/instrumenpoche/ à partir des commentaires du fichier src/js/modules/Alea2iep.js et dont la page d'accueil sera créée à partir de jsdoc/iep.md.
  • tout.json va générer une documentation dans le dossier documentation/tout à partir des commentaires de tous les fichiers du dossier src/js/.

Lorsqu'on lance pnpm run doc:show on atterrit sur la page d'accueil du base.json qui contient en début de page des liens vers les trois autre documentations.