|
|
Arcane
v4.1.0.0
Documentation développeur
|
|
|
|
Arcane
v4.1.0.0
Documentation développeur
|
Lors de la réécriture/restructuration de cette documentation, certaines conventions ont été établies pour avoir une doncumentation homogène, simple à lire (à la fois son code source et son rendu final).
La documentation se présente ainsi : (commande tree avec quelques coupes)
Toute la partie thème pour Doxygen se trouve dans le dossier theme. La documentation générale est répartie en chapitre, sous-chapitre, sous-sous-chapitre, &c.
Prenons le chapitre getting_started pour l'exemple. Tout ce chapitre se trouve dans le dossier chap_getting_started. Il n'y a pas de numérotations sur ces dossiers pour éviter d'avoir à tout changer dans le fichier userdoc.doxyfile en cas de changement de position.
Dans un chapitre, nous avons plusieurs fichiers markdown (.md). Le premier doit être un sommaire et nommé 0_nom_du_chapitre.md. Ce sommaire permet de lister les \subpage pour que Doxygen puisse créer les liaisons et la structure de la documentation.
Exemple, le fichier 0_getting_started.md :
Première ligne, on a le titre de notre chapitre et son tag (pour pouvoir être référencé dans d'autres pages). On utilise les # pour désigner les titres (comme dans les markdowns). La première ligne est toujours un titre h1 (1 seul #). Le tag est entre acolades et débute par un croisillon. Le nom du tag est structuré comme ceci : arcane_nom_du_chapitre.
Troisième ligne, on a une description sommaire du chapitre.
Les trois lignes suivantes représentent le sommaire du chapitre. On a une liste numérotée de \subpage. À coté de \subpage, on a le tag d'une page du chapitre.
À la ligne 10, on a une ligne de séparation (voir doc de markdown).
Enfin, on a une partie de html pour faire apparaitre des boutons. Deux boutons maximum : un bouton back et un bouton next. Ici, on n'a qu'un bouton next. Entre les <span>, on doit mettre une référence à une page (et pas un \subpage !). La partie CSS s'occupera de faire apparaitre les boutons correctement.
Prenons maintenant le fichier suivant : 1_about.md (un peu modifié pour cette explication) :
D'abord, la première ligne est semblable à la première ligne du fichier précédent. Titre de niveau 1 (1 seul #). On commence avec le nom de la page puis son tag. Le tag est structuré comme ceci : arcane_nom_du_chapitre_nom_de_la_page.
Ensuite, on retrouve la table des matières ([TOC]) qui sera généré par doxygen si besoin.
Après, on a des titres de niveau 2 et 3. Le tag est toujours construit de la même manière :
arcane_nom_du_chapitre_nom_de_la_page_titre_de_la_section_niveau2_titre_de_la_section_niveau3,...
Pour finir, on retrouve la ligne horizontale et les boutons back et next avec des \ref entre les <span>.
Enfin, les sous-chapitres. C'est à peu près le même principe.
Dans le chapitre example, on a :
Quand on veut faire un sous-chapitre, on créé un dossier subchap_nom_du_sous_chapitre dans le dossier du chapitre parent et on créé un fichier 1_nom_du_sous_chapitre.goto.
Ce fichier permet de situer le sous-chapitre par rapport aux autres pages (pour nous, doxygen n'en a pas besoin).
Voyons le fichier 0_concret_example.md :
Les tag seront structurés comme ça : arcane_nom_du_chapitre_nom_du_sous_chapitre_nom_de_la_page_titre_de_la_section_niveau2,...
A part ça, on reprend les règles précédentes.
Pour les images, elles doivent être mises avec le (sous-) chapitre correspondant, dans un dossier img. Ce dossier devra être répertorié dans la partie IMAGE_PATH du userdoc.doxyfile.
Les morceaux de code sont à mettre entre trois "`" (AltGr+7 sur clavier azerty) ou entre trois "~" (AtlGr+2 sur clavier azerty). (Voir doc markdown pour plus d'infos).
Une fois votre chapitre ajouté, il faudra ajouter le ou les dossiers des chapitres et des sous-chapitres dans le userdoc.doxyfile, partie INPUT.
Deux macros ont été défini : \arcane{} et \arccore{}. Elles permettent de lier une classe ou une méthode sans mettre le namespace Arcane:: ou Arccore:: et sans l'afficher.
Exemple :
Sans namespace : Cell -- Sans macro : Arcane::Cell -- Avec macro : \\arcane{Cell}
donne :
Sans namespace : Cell – Sans macro : Arcane::Cell – Avec macro : Cell
Dans la partie Changelog, il est possible d'utiliser la macro \pr{} pour rediriger créer un lien vers la pull request sur GitHub. Exemple :
Avec la dernière version du thème "Doxygen Awesome", nous avons la possibilité d'ajouter des onglets dans la documentation. Exemple :
Voici le code des onglets affichés au-dessus :
Doxygen est assez capricieux pour le html. Pour mettre plusieurs lignes dans un onglet, il faut soit utiliser la balise <br>, soit mettre le tout dans une <div>, avec tout le contenu de la div indentée. Exemple :
Onglet 2
Il est possible d'utiliser les balises <details><summary> dans la documentation pour réduire un bout de texte.
Exemple :
Contenu réduit.
1.13.2