1. Sections et liens hypertexte#
1.1. Page d’entête#
Un document est identifié sa clé documentaire. Cette clé doit être fournie par le responsable de la documentation.
Cette clé doit aussi être le nom du répertoire de ce document dans
source/manuals/man_x/x0/x0.00.00 où x est a, r, d, u, v, m ou s pour salome_meca.
La page principale doit être nommée index.rst dans ce répertoire.
Cette page doit contenir :
la référence vers le document :
.. _x0.00.00:,le titre du document, commençant par
**x0.00.00**(utilisé pour le menu global),l’objet/résumé du document,
la table des matières donnant accès aux différentes pages du document.
Exemple de index.rst:
.. _r5.03.01:
**r5.03.01** Algorithme non linéaire quasi-statique (STAT_NON_LINE)
===================================================================
**Résumé :**
L'opérateur STAT_NON_LINE [:external:ref:`u4.51.03 <u4.51.03>`] permet...
etc.
.. toctree::
:hidden:
self
.. toctree::
:maxdepth: 2
:numbered:
Presentation
Methode_de_Newton
- Commandes
Pour les notices d’utilisation des commandes (u4 et u7), le titre du document doit avoir ce format afin d’extraire automatiquement la liste des commandes:
**u4.41.01** Opérateur AFFE_MODELE ==================================
- Cas-tests
De même, pour les notes de validation des cas-tests, le format du titre est imposé de manière à construire la liste des cas-tests:
**v6.01.102** SSNA102 - Contact multicorps élastiques ======================================================
1.2. Niveaux de sections#
Les titres des sections sont définis en les soulignant ou encadrant avec des caractères spéciaux.
Titre de la page
================
C'est l'équivalent d'une *Titre de niveau 1*.
Titre de section
----------------
C'est l'équivalent d'une *Titre de niveau 2*.
Titre de sous-section
~~~~~~~~~~~~~~~~~~~~~
C'est l'équivalent d'une *Titre de niveau 3*.
On peut aussi utiliser l’encadrement :
================
Titre de la page
================
1.3. Liens hypertextes#
1.3.1. Vers les sections d’un document#
Il faut définir la référence juste avant la section :
.. _r5.03.01-prediction-euler:
Phase de prédiction d’Euler
---------------------------
Note
Afin d’éviter les collisions entre les références des différents documents,
on propose de mettre systèmatiquement la clé du document comme préfixe.
Ne pas mettre .. _bibliographie: mais .. _r5.03.01-bibliographie:.
Préférer les tirets « - » au souligné « _ » pour séparer les éléments, ce dernier ayant un sens particulier selon le contexte.
Puis y faire référence avec la directive :ref: :
Ceci produit un lien vers la section :ref:`d8.00.01-liens`.
Voir la section :ref:`r5.03.01-prediction-euler` d'un autre document
ou encore, consulter le document :ref:`r5.03.01 <r5.03.01>`.
Ce qui donne :
Ceci produit un lien vers la section Liens hypertextes au sein de ce document. Voir la section r5.03.01-prediction-euler d’un autre document… ou encore, consulter le document r5.03.01.
On peut aussi utiliser :external:ref: pour référencer un autre document mais
ce n’est pas nécessaire.
- Remarques
Il n’est pas nécessaire d’ajouter une référence avant chaque section. On ne le fait que quand on en a besoin.
Il faut éviter d’utiliser les liens RST
`Niveaux de sections`_qui sont plus compliqués à maintenir. Il faut modifier le lien ET les références dès qu’on modifie la section, il y a plus de risque de conflits….
1.3.2. Liens vers les équations#
Voir le paragraphe Équations pour la définition des équations.
Note
Il n’y a pas de numérotation globale des équations.
Par exemple :
.. math:: e^{i\pi} + 1 = 0
:label: eq-euler
On insère un lien vers cette équation avec :eq:`eq-euler`, ce qui donne (1.1).
Le format est <numéro de section>.<numéro de l'équation dans la section>.
Pour faire référence à une équation d’une page différente et, a fortiori, d’un autre document, on peut ajouter un label :
Si :eq:`eq-chaleur` est ambigü, on préférera :ref:`l'équation de la chaleur <d8.00.01-eq-chaleur>`
Si (2.1) est ambigü, on préférera l’équation de la chaleur.
1.3.3. Liens vers les figures#
Voir le paragraphe Figures pour voir l’illustration du Schéma de Newton ou de la figure :d8.00.01-fig-newton.
1.3.4. Liens vers les références bibliographiques#
On utilise les citations de Sphinx de cette manière :
On peut citer [bib1]_ ou encore [bib2]_.
Ce qui donne :
On peut citer [bib1] ou encore [bib2].
Voir le paragraphe Bibliographie pour la liste des références.