Arcane  v3.16.2.0
Documentation développeur
•Tout Classes Espaces de nommage Fichiers Fonctions Variables Définitions de type Énumérations Valeurs énumérées Amis Macros Groupes Pages Concepts
Comment écrire de la documentation

Table des matières

Introduction

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).

Structure

La documentation se présente ainsi : (commande tree avec quelques coupes)

1framework/arcane/doc/
2├── cea_ifpen_logo.png
3├── changelog.md
4├── chap_core_types
5│   ├── 0_core_types.md
6│   ├── 1_module.md
7│   ├── 2_variable.md
8│   ├── ...
9│   └── subchap_caseoptions
10│   ├── 0_caseoptions.md
11│   ├── 1_intro.md
12│   ├── 2_struct.md
13│   └── ...
14├── chap_debug_perf
15│   ├── 0_debug_perf.md
16│   ├── 1_check_memory.md
17│   ├── 2_profiling.md
18│   └── ...
19├── chap_examples
20│   ├── 0_examples.md
21│   ├── 1_simple_example.goto
22│   ├── 2_concret_example.goto
23│   ├── subchap_concret_example
24│   │   ├── 0_concret_example.md
25│   │   ├── 1_struct.md
26│   │   ├── 2_config.md
27│   │   ├── ...
28│   │   └── img
29│   │   ├── QAMA_schema.odg
30│   │   └── QAMA_schema.svg
31│   └── subchap_simple_example
32│   ├── 0_simple_example.md
33│   ├── 1_struct.md
34│   ├── 2_module.md
35│   ├── ...
36│   └── img
37│   ├── HW_schema.odg
38│   ├── HW_schema.svg
39│   └── ...
40├── chap_getting_started
41│   ├── 0_getting_started.md
42│   ├── 1_about.md
43│   ├── 2_basicstruct.md
44│   └── ...
45├── how_write_doc.md
46├── theme
47│   ├── custom.css
48│   ├── doxygen-awesome-theme
49│   │   └── ...
50│   ├── header.html
51│   ├── script-num-lines-code.js
52│   └── script-resize.js
53├── user
54│   ├── cleanup_v2.dox
55│   └── usermanual.md
56└── userdoc.doxyfile

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 :

1# Débuter avec %Arcane {#arcanedoc_getting_started}
2
3Vous débutez sur %Arcane ? Ce chapitre devrait vous donner les notions de bases.
4
5Sommaire de ce chapitre :
61. \subpage arcanedoc_getting_started_about
72. \subpage arcanedoc_getting_started_basicstruct
8
9
10____
11
12<div class="section_buttons">
13<span class="next_section_button">
14\ref arcanedoc_getting_started_about
15</span>
16</div>

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) :

1# Qu'est-ce que %Arcane ? {#arcanedoc_getting_started_about}
2
3[TOC]
4
5## Arcon, Arccore ? {#arcanedoc_getting_started_about_arcall}
6### Arcon {#arcanedoc_getting_started_about_arcall_arcon}
7
8...Texte...
9
10## Framework ? {#arcanedoc_getting_started_about_framework}
11
12...Texte...
13
14
15____
16
17<div class="section_buttons">
18<span class="back_section_button">
19\ref arcanedoc_getting_started
20</span>
21<span class="next_section_button">
22\ref arcanedoc_getting_started_basicstruct
23</span>
24</div>

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 :

1├── chap_examples
2│   ├── 0_examples.md
3│   ├── 1_simple_example.goto
4│   ├── 2_concret_example.goto
5│   ├── subchap_concret_example
6│   │   ├── 0_concret_example.md
7│   │   ├── 1_struct.md

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 :

1# Exemple concret {#arcanedoc_examples_concret_example}
2
3
4Ce sous-chapitre présente un exemple concret appelé `Quicksilver %Arcane Mini-App`.
5
6Il est recommendé d'avoir lu le sous-chapitre précédent \ref arcanedoc_examples_simple_example
7pour bien comprendre ce qui suit, car certaines choses ne seront pas répétées ici.
8
9Sommaire de ce sous-chapitre :
101. \subpage arcanedoc_examples_concret_example_struct
11
12
13____
14
15<div class="section_buttons">
16<span class="back_section_button">
17\ref arcanedoc_examples
18</span>
19<span class="next_section_button">
20\ref arcanedoc_examples_concret_example_struct
21</span>
22</div>

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 :

PR #530

Avec la dernière version du thème "Doxygen Awesome", nous avons la possibilité d'ajouter des onglets dans la documentation. Exemple :

  • Coucou ! Voici l'onglet n°1 !
  • Recoucou ! Voici l'onglet n°2 !

Voici le code des onglets affichés au-dessus :

1<div class="tabbed">
2
3- <b class="tab-title">Onglet 1</b>
4Coucou ! Voici l'onglet n°1 !
5
6- <b class="tab-title">Onglet 2</b>
7Recoucou ! Voici l'onglet n°2 !
8
9</div>

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 :

  • Coucou ! Voici l'onglet n°1 !
    Coucou ! Voici l'onglet n°1 !
    Coucou ! Voici l'onglet n°1 !

  • Recoucou ! Voici l'onglet n°2 !
    Recoucou ! Voici l'onglet n°2 !
    Recoucou ! Voici l'onglet n°2 !
1<div class="tabbed">
2
3- <b class="tab-title">Onglet 1</b>
4Coucou ! Voici l'onglet n°1 !<br>
5Coucou ! Voici l'onglet n°1 !<br>
6Coucou ! Voici l'onglet n°1 !
7
8
9- <b class="tab-title">Onglet 2</b>
10<div>
11 Recoucou ! Voici l'onglet n°2 !
12
13 Recoucou ! Voici l'onglet n°2 !
14
15
16
17 Recoucou ! Voici l'onglet n°2 !
18</div>
19
20</div>

Il est possible d'utiliser les balises <details><summary> dans la documentation pour réduire un bout de texte.

Exemple :

1<details>
2 <summary>Titre</summary>
3 Contenu réduit.
4</details>
Titre

Contenu réduit.