.. _d8.00.01-sections-refs: Sections et liens hypertexte ============================ 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``: .. code-block:: 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 `] 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: .. code-block:: rst **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: .. code-block:: rst **v6.01.102** SSNA102 - Contact multicorps élastiques ====================================================== Niveaux de sections ------------------- Les titres des sections sont définis en les soulignant ou encadrant avec des caractères spéciaux. .. code-block:: rst 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 : .. code-block:: rst ================ Titre de la page ================ .. _d8.00.01-liens: Liens hypertextes ----------------- Vers les sections d'un document ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Il faut définir la référence juste avant la section : .. code-block:: rst .. _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:`` : .. code-block:: rst 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 `. Ce qui donne : Ceci produit un lien vers la section :ref:`d8.00.01-liens` au sein de ce document. Voir la section :ref:`r5.03.01-prediction-euler` d'un autre document... ou encore, consulter le document :ref:`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.... Liens vers les équations ~~~~~~~~~~~~~~~~~~~~~~~~ Voir le paragraphe :ref:`d8.00.01-equations` pour la définition des équations. .. note:: Il n'y a pas de numérotation globale des équations. Par exemple : .. code-block:: rst .. math:: e^{i\pi} + 1 = 0 :label: eq-euler .. math:: e^{i\pi} + 1 = 0 :label: eq-euler On insère un lien vers cette équation avec ``:eq:`eq-euler```, ce qui donne :eq:`eq-euler`. Le format est ``.``. Pour faire référence à une équation d'une page différente et, a fortiori, d'un autre document, on peut ajouter un label : .. code-block:: rst Si :eq:`eq-chaleur` est ambigü, on préférera :ref:`l'équation de la chaleur ` Si :eq:`eq-chaleur` est ambigü, on préférera :ref:`l'équation de la chaleur `. Liens vers les figures ~~~~~~~~~~~~~~~~~~~~~~ Voir le paragraphe :ref:`d8.00.01-figures` pour voir l'illustration du :ref:`d8.00.01-fig-newton` ou de la figure :`d8.00.01-fig-newton`. .. _d8.00.01-sections-refs-biblio: Liens vers les références bibliographiques ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On utilise les *citations* de Sphinx de cette manière : .. code-block:: rst On peut citer [bib1]_ ou encore [bib2]_. Ce qui donne : On peut citer [bib1]_ ou encore [bib2]_. Voir le paragraphe :ref:`d8.00.01-biblio` pour la liste des références.