d8.00.01 Consignes de rédaction des documents RST#

Résumé :

Ce document fournit quelques consignes pour la rédaction des documents au format reStructuredText et des exemples de mise en oeuvre.

Contenu et mise en forme#

Paragraphes#

En RST, les paragraphes sont simplement des blocs de texte séparés par un saut de ligne.

Pour faciliter la relecture et visualiser rapidement les changements faits dans un document, on préconise de ne pas écrire des lignes de plus d’une centaine de caractères. Cependant, la conversion automatique des documents depuis le format ODT n’a pas respecté cette consigne.

Évitez de mettre « dans code_aster » ou « dans aster » dans la documentation. On se doute bien que c’est dans code_aster, puisqu’on est dans la documentation de code_aster ! À ce propos, jurisprudence Christophe-MMN.Durand, on dit « code_aster » pas « LE code_aster »).

Les tableaux « versions du document » (en particulier dans les doc R) sont supprimés. L’historique des versions est naturellement porté par le système de dépôt Git. Il est donc inutile de compléter ce tableau qui sera supprimé lors de la validation des documents.

Il faut éviter au maximum de mettre des extraits de mise en données dans la documentation. En effet, ces extraits ne sont pas modifiés si la syntaxe évolue et ils deviennent syntaxiquement incorrect. Les mises en données, on les met dans les cas-tests.

Pour les valeurs numériques, il faut toujours mettre un chiffre après le point décimal (1.0 et non 1.) car 1. désigne le début d’une liste numérotée.

Mise en forme#

L’objet du RST est justement de faire un minimum de mise en forme pour conserver une documentation homogène et lisible même en texte brut. Le fichier RST lui-même est lisible.

Utiliser :

un astérisque : *text* pour un texte en italique,
deux astérisques : **text** pour un texte en gras,
des accents graves : ``text`` pour un extrait de code.

La mise en forme en utilisant du code html est interdite.

Remarque

On écrit les mots-clés normalement : MODELE. Il n’est pas nécessaire d’écrire MODELE.

Le paragraphe des commandes est généré automatiquement. Dans les documentations des commandes, ne pas répéter la syntaxe dans la description de chaque mot-clé. C’est redondant et parfois pas à jour.

Pour les blocs de code, on utilise :

.. _d8.00.01-myfunction:

.. code-block:: python
    :caption: Exemple de code Python

    def myfunction(x):
        """Example function."""
        return x + 1

Ce qui donne :

Code source 3 Exemple de code Python#

def myfunction(x):
    """Example function."""
    return x + 1

On peut utiliser :caption:. La légende est alors affichée, le bloc est numéroté et on peut ainsi y faire référence en affichant ce numéro.

Voir un exemple de Exemple de code Python ou le Code source 3.

est obtenu avec :

Voir un exemple de :ref:`d8.00.01-myfunction` ou le :numref:`d8.00.01-myfunction`.

Équations#

Les équations sont saisies au format LaTeX.

Il existe de nombreux éditeurs en ligne:

Le site Hostmath.
La documentation sur LaTeX fournie par Overleaf est l’une des plus complètes
Le site Detexify est très pratique: vous dessinez votre symbole avec la souris et il vous trouve la commande LaTeX correspondante

Les équations peuvent être séparées ou bien en ligne dans le texte.

L’équation de la chaleur est :

Les équations :eq:`eq-chaleur` et :eq:`eq-fourier` sont extraites du
document :ref:`r5.02.01 <r5.02.01>` :

.. _d8.00.01-eq-chaleur:

.. math::
    :label: eq-chaleur

    -div(-\lambda \nabla T(r,t)) + s(r,t) = \rho {C}_{p} \frac{\partial T(r,t)}{\partial t}

.. math::
    :label: eq-fourier

    q(r,t)=-\lambda \nabla T(r,t)

avec :math:`\lambda` la conductivité thermique, :math:`\rho {C}_{p}` la chaleur
volumique à pression constante.

Ce qui donne :

Les équations (5015) et (5016) sont extraites du document r5.02.01 :

(5015)#\[-div(-\lambda \nabla T(r,t)) + s(r,t) = \rho {C}_{p} \frac{\partial T(r,t)}{\partial t}\]

(5016)#\[q(r,t)=-\lambda \nabla T(r,t)\]

avec \(\lambda\) la conductivité thermique, \(\rho {C}_{p}\) la chaleur volumique à pression constante.

Il est utile d’ajouter la référence .. _d8.00.01-eq-chaleur: pour insérer un lien vers une équation depuis une autre page ou document.

Règles générales de typographie des équations#

LaTeX n’est pas un éditeur WYSIWYG, le concept fondamental (comme RST) est de séparer le fond de la forme. Ne faites donc pas de mise en forme manuelle (ajouts d’espaces, de retour à la ligne, etc.).

Il est certain que RST et le générateur HTML embarque les packages \amsmath` et leurs cousins. Ces packages ont été développés par l’American Mathematical Society, ce qui donne accès aux caractères et méthodes « normalisées » dans la communauté (y compris françaises).

Il est inutile de numéroter toutes les équations.

Il faut éviter de donner des directives de mise en forme de polices. Par exemple \mathbm{=} est inutile.

Si vous avez besoin de texte dans une équation, utilisez l’environnement \text{ tagada }. C’est important pour la gestion des espaces (remarquez la présence des espaces) et des caractères accentués.

Pour ajouter des espaces dans une équation (par ordre croissant d’espacement): \,, \quad et \qquad. Évitez les espaces insécables en mode math (comme ~) ça contraint trop l’algorithme de rendu de LaTeX. Les directives de mise en forme en mode math se font sous fomes d’environnements dédiés (array par exemple).

Prenez l’habitude d’utiliser \lbrace \rbrace ou \left( et \right), ainsi la hauteur des parenthèses pourra s’ajuster si vous changez le contenu. N’utilisez pas / pour une division, mais \frac. Par exemple \frac{1}{3} plutôt que 1/3.

Pour les lettres grecques (et les symboles mathématiques en général) en gras, \mathbf{\sigma} ne marchera pas, il faut \boldsymbol{\sigma}.

Comparez: \(\boldsymbol{\sigma}\) (avec \boldsymbol) et \(\mathbf{\sigma}\) (avec \mathbf).

Pour les (petites) déformations, le symbole \varepsilon (\(\varepsilon\)) est plus conforme aux habitudes des mécaniciens que \epsilon (\(\epsilon\)) .

la directive \cdot est réservé au produit scalaire, ne l’utilisez pas en dehors de ce contexte précis. De même, il est recommandé de ne pas mettre de . (point multiplicatif) entre des scalaires par exemple, Si vous voulez que ce soit plus propre (en particulier entre lettres grecques qui sont en italique), vous pouvez insérez une espace de type \,.

Pour écrire un ensemble d’équations, voici un exemple de syntaxe:

.. math::
    \left \lbrace  \begin{array}{ll}
    eq1 & \text { pour cette valeur} \\
    eq2 & \text { pour l'autre valeur}
    \end{array}  \right.

Ce qui donne:

\[\begin{split}\left \lbrace \begin{array}{ll} eq1 & \text { pour cette valeur} \\ eq2 & \text { pour l'autre valeur} \end{array} \right.\end{split}\]

Les opérateurs mathématiques doivent être déclarés de la manière suivante

.. math::
    \DeclareMathOperator{\dist}{dist}

Ne pas écrire mathit{dist} par exemple. Comparez le résultat:

\[\DeclareMathOperator{\dist}{dist} \dist \text{ avec la déclaration d'opérateur } \mathit{dist} \text{ avec la mise en forme dédiée}\]

Les barres verticales sont définies par \vert et \Vert, ne pas utilisez \parallel et \mid. Comparez le rendu:

\[\begin{split}\left \lbrace \begin{array}{ll} \text{Barre verticale \mid :} \mid & \text{Barre verticale \vert :} \vert \\ \text{Double barre verticale \parallel :} \parallel & \text{Double barre verticale \Vert :} \Vert \\ \end{array} \right.\end{split}\]

Ces barres verticales permettent en particulier de désigner les normes :

\Vert \underline{x} \Vert donne \(\Vert \underline{x} \Vert\) \parallel \underline{x} \parallel donne \(\parallel \underline{x} \parallel\)

Et des valeurs absolues:

\vert {x} \vert donne \(\vert {x} \vert\) \mid {x} \mid donne \(\mid {x} \mid\)

Feuille de styles des équations#

Il est conseillé d’utiliser la feuille de styles des équations qui regroupe les notations les plus fréquentes en mécanique, ce qui permet d’avoir une certaines homogénéité dans la documentation.

Pour cela, inclure en tête de chaque fichier RST (sur la 2ème ligne juste après la référence principale par exemple) :

.. include:: ../../../../../_cache/math_styles.rst

On peut ainsi utiliser des notations normalisées pour :

vecteur	\(\vector{u}\)	`\vector{u}`
matrice	\(\tensTwo{A}\)	`\tensTwo{A}`
norme euclidienne	\(\normEucl{\vector{v}}\)	`\normEucl{\vector{v}}`

Exemple :

(5017)#\[\begin{split}\left \lbrace \begin{array}{ll} & - \vector{div} \left( \tensTwo{P} \right) = \underline {f} & \text{dans} \, \Omega\\ & \vector{u} = \vector{u}_d & \text{sur} \, \Gamma_{D} \\ & \tensTwo{P} \, \vector{N} = \vector{t}_{N} & \text{sur} \, \Gamma_{N} \\ & P_{n} \le 0, \, g_{n}(\vector{u}) \ge 0, \, g_{n}(\vector{u}) \, P_{n} =0 & \text{sur} \, \Gamma_{C} \\ & \normEucl{\vector{P}_{\tau}} \le 0 \text{ si } \vector{v}_{\tau} = \vector{0} \text{ et } \vector{P_{\tau}} = -s \frac{\vector{v}_{\tau}}{\normEucl{\vector{v}_{\tau}}} & \text{sur} \, \Gamma_{C} \\ \end{array} \right .\end{split}\]

Important: Ne modifiez pas ce fichier de styles de votre propre initiative, si vous voulez l’enrichir ou le modifier, demandez au responsable de la documentation de référence.

Figures#

.. figure:: ../../../man_r/r5/r5.03.01/images/Object_69.svg
    :name: d8.00.01-fig-newton
    :width: 30%

    Schéma de Newton

Ce qui donne :

../../../../_images/Object_69.svg — Fig. 795 Schéma de Newton#

La directive figure permet de définir une légende « Schéma de Newton », contrairement à la directive image. L’option :name: définit une référence que l’on utilise classiquement.

Lien vers la figure :ref:`d8.00.01-fig-newton` ou :numref:`d8.00.01-fig-newton`.

Ce qui donne :

Lien vers la figure Figure 2.2.1-a ou Fig. 192.

Image adaptée au thème light/dark#

Par défaut, l’image est automatiquement ajustée pour s’adapter au mieux au thème. Un fond blanc est ajouté et la luminosité est réduite :

On peut choisir une image pour le fond clair et une pour le fond sombre en utilisant l’attribut :class: only-light ou :class: only-dark. On affiche l’une ou l’autre des images selon le thème :

Si l’on considère que l’image soit être affichée telle quelle, sans ajustement, quelque soit le thème, on utilise :class: dark-light (il s’agit des deux images précédentes sans ajustement) :

Listes à puces, numérotées#

Exemple :

* Un premier élément
* Un deuxième

  * Avec un sous-niveau

* Le troisième et dernier élément.

Ce qui donne :

Un premier élément
Un deuxième
- Avec un sous-niveau
Le troisième et dernier élément.

Avec numérotation automatique :

#. Un premier élément
#. Un deuxième
#. Le troisième et dernier élément.

Ce qui donne :

Un premier élément
Un deuxième
Le troisième et dernier élément.

Remarques#

Pour ajouter une remarque, on fait simplement :

Remarque
    Il convient de préciser ceci ou cela.

Ce qui donne :

Remarque: Il convient de préciser ceci ou cela.

Différents types de tableaux#

Tableau simple#

Pour les petits tableaux, on peut utiliser la forme la plus simple :

.. _d8.00.01-tab-simp:

.. table:: Paramètres matériaux de l'acier
   :widths: auto

   ===========  ========
    Paramètre    Valeur
   ===========  ========
   E            2.1e9
   :math:`\nu`  0.3
   ===========  ========

Ce qui donne :

Tableau 186 Paramètres matériaux de l’acier#
Paramètre	Valeur
E	2.1e9
\(\nu\)	0.3

La présence du titre dans le tableau le numérote automatiquement. Pour y faire référence, on utilise :

Voir les :ref:`d8.00.01-tab-simp` ou :numref:`d8.00.01-tab-simp`.

Ce qui donne :

Voir les Paramètres matériaux de l’acier ou Tableau 186.

Tableau csv#

Dès que le tableau est plus compliqué, le format CSV est préférable :

.. csv-table:: Paramètres matériaux de l'acier
    :header: "Paramètre", "Valeur"
    :widths: 50, 50

    E, 2.1e9
    :math:`\nu`, 0.3
    ":math:`\lambda`, :math:`\mu`", "étant 'connu' que :math:`\frac{E \nu}{(1+\nu)(1-2\nu)}`,
    soit 1.21e9

    et :math:`\frac{E}{2(1+\nu)}`, soit 0.81e9"

Note

Les double-quotes " permettent de délimiter le contenu des colonnes (obligatoire quand une virgule figure dans le contenu de la cellule).

On peut revenir la ligne (entre les ") et sauter une ligne pour démarrer un nouveau paragraphe.

Ce qui donne :

Tableau 187 Paramètres matériaux de l’acier#
Paramètre	Valeur
E	2.1e9
\(\nu\)	0.3
\(\lambda\), \(\mu\)	étant “connu” que \(\frac{E \nu}{(1+\nu)(1-2\nu)}\), soit 1.21e9 et \(\frac{E}{2(1+\nu)}\), soit 0.81e9

Tableaux en listes#

On peut aussi utiliser ce format utilisant deux niveaux de listes à puces :

.. list-table:: Paramètres matériaux de l'acier
    :widths: 50, 50
    :header-rows: 1

    * - Paramètre
      - Valeur
    * - E
      - 2.1e9
    * - :math:`\nu`
      - 0.3
    * - :math:`\lambda`, :math:`\mu`
      - étant 'connu' que :math:`\frac{E \nu}{(1+\nu)(1-2\nu)}`,
        soit 1.21e9

        et :math:`\frac{E}{2(1+\nu)}`, soit 0.81e9

Ce qui donne :

Tableau 188 Paramètres matériaux de l’acier#
Paramètre	Valeur
E	2.1e9
\(\nu\)	0.3
\(\lambda\), \(\mu\)	étant “connu” que \(\frac{E \nu}{(1+\nu)(1-2\nu)}\), soit 1.21e9 et \(\frac{E}{2(1+\nu)}\), soit 0.81e9

Bibliographie#

Les références bibliographiques sont définies de cette manière :

.. [bib1]   Mialon, P. (1986). Éléments d'analyse et de résolution numérique des relations
   de l'élasto-plasticité, EDF R&D, Rapport interne .

.. [bib2]   Simo J.C., Hughes T.J.R., Computational Inelasticity, Mechanics and Materials,
   Interdisciplinary Applied Mathematics Vol. 7 , Edition Springer-Verlag, New York, 1998.

Ce qui donne :

[bib1]

Mialon, P. (1986). Éléments d’analyse et de résolution numérique des relations de l’élasto-plasticité, EDF R&D, Rapport interne .

[bib2]

Simo J.C., Hughes T.J.R., Computational Inelasticity, Mechanics and Materials, Interdisciplinary Applied Mathematics Vol. 7 , Edition Springer-Verlag, New York, 1998.

Voir d8.00.01-sections-refs-biblio pour y faire référence.

Note

On ne devrait pas citer dans la bibliographie d’autres documents faisant partie de la documentation.

Génération automatique#

Génération automatique du paragraphe syntaxe#

Le paragraphe Syntaxe des commandes des documents u4/u7 est généré automatiquement à partir du catalogue de la commande.

Quand de nouveaux mots-clés sont ajoutés, il suffit de générer le nouveau paragraphe et remplacer le précédent, en général, dans le fichier Syntaxe.rst.

Pour cela, il suffit au développeur d’avoir construit une version de développement avec le catalogue de commandes modifié et de lancer le cas-test vocab01c en définissant la variable d’environnement CMD:

make vocab01c CMD=FIN
# ou
./waf test -n vocab01c CMD=FIN

Cette exécution produit le fichier vocab01c.mpi.release.output dans un répertoire temporaire (le nom complet est affiché dans le terminal). Au milieu de ce fichier, on trouve les lignes à copier entre les lignes de +++++. Enregistrer ces lignes (sans les +++++) dans le fichier Syntaxe.rst.

Remarque

On trouve dans certains documents des extraits de la syntaxe globale.

Avant d’ajouter un tel extrait, il faut se demander si cela apporte quelque chose par rapport à cliquer sur Syntaxe dans le menu de gauche. Pour les mots-clés simples, il est inutile de rappeler la syntaxe du mot-clé.

Exemple:

Syntaxe

FIN(
    ◇ RETASSAGE = / "OUI",
                  / "NON" (par défaut),
    ◇ INFO_RESU = / "OUI",
                  / "NON" (par défaut),
    ◇ PROC0 = / "OUI",
              / "NON",
)

◆ : obligatoire
◇ : optionnel
⟐ : présent par défaut
& : ensemble
/ : un seul parmi
| : plusieurs choix possibles

Reprise de la conversion automatique#

On liste dans cette section les erreurs connues de conversion et on indique la méthode à suivre pour les corriger.

Les documents odt étaient moins WYSIWYG qu’il n’y paraissait et plus What You See Is A Very Small Part Of What You Get! En effet, après des années de modifications successives, de nombreux blocs de texte ont superposé des mises en forme successives. Par exemple, le changement de police sur un même mot fait en deux temps (ce qui occasionnait déjà en odt des mots coupés). La conversion automatique a donc « nettoyé » ce type de mise en forme avec parfois quelques imperfections.

Les zones de texte en police Courier New représentaient de la syntaxe. Le texte n’étant pas typé, les lignes/paragraphes n’étant pas liés entre eux, la conversion a souvent découpé ces paragraphes en plusieurs blocs…

Accessibilité#

Problème en cours d’analyse : Lorsque la page n’est pas assez large, certains documents (de Validation ou salome_meca) ne sont plus accessibles par les menus. Au delà d’une certaine limite (sur mobile par exemple), les menus disparaissent.

Solution: Accéder à la liste des documents par manuel depuis la page d’accueil.

Correction des blocs de syntaxe#

Remarque: Le paragraphe des documents u4/u7 est maintenant généré automatiquement. Voir Génération automatique.

Exemple :

source/manuals/man_d/d9/d9.02.02/Les_impressions.rst:129: ERROR: Undefined substitution referenced: "G".

Dans le document, on peut voir que la ligne 129 correspond à :

*   le nom de l'objet (éventuellement complété par le numéro d'objet de collection).

|G| 0| 1| -2| 69888784|U| 11| D| ________GLOBALE ________$$CARA

En RST, |G| correspond à la substitution de G. Ici, il suffit de déclarer qu’il s’agit d’un bloc de texte brut :

*   le nom de l'objet (éventuellement complété par le numéro d'objet de collection).

.. code-block:: text

    |G| 0| 1| -2| 69888784|U| 11| D| ________GLOBALE ________$$CARA

Remarques

.. code-block:: python: Avoir un bloc complet extrait d’un fichier de commandes est rarement une très bonne idée (difficile de le garder à jour). Mais dans ce cas, on peut utiliser la coloration Python pour le rendu du bloc.

.. code-block:: text: Pour du texte brut, le préciser ainsi.

Correction des tableaux#

Le format des tableaux choisi par la conversion automatique est le plus souple mais trop compliqué à maintenir !

Exemple :

Cas particulier des critères d'égalité (ou de non égalité) pour des nombres "flottants" :

+---------+------------------------------------------------------------------------------------+
| ‘EGAL’  | égalité “exacte” des 2 nombres flottants                                           |
+---------+------------------------------------------------------------------------------------+
| ‘ABSO’  | égalité des 2 nombres flottants à un epsilon près (eps) en comparaison absolue :   |
|         | vrai si |x1-x2| < eps                                                         |
+---------+------------------------------------------------------------------------------------+
| ‘RELA’  | égalité des 2 nombres flottants à un epsilon près (eps) en comparaison relative :  |
|         | vrai si |x1-x2| < eps * |x1|                                              |
+---------+------------------------------------------------------------------------------------+

Ici, il y aurait deux erreurs :

le mauvais alignement des caractères | en fin de ligne du tableau,
et la mauvaise substitution (paragraphe précédent mais dans un autre contexte).

source/manuals/man_d/d8/d8.00.01/conversion.rst:79: ERROR: Malformed table.
source/manuals/man_d/d8/d8.00.01/conversion.rst:85: ERROR: Undefined substitution referenced: "x1-x2".

Il est préférable d’utiliser un format plus simple (csv):

.. csv-table::

    ‘EGAL’, égalité “exacte” des 2 nombres flottants
    ‘ABSO’, égalité des 2 nombres flottants à un epsilon près (eps) en comparaison absolue : vrai si :math:`|x1-x2| < eps`
    ‘RELA’, égalité des 2 nombres flottants à un epsilon près (eps) en comparaison relative : vrai si :math:`|x1-x2| < eps * |x1|`

Ce qui donne :

‘EGAL’	égalité “exacte” des 2 nombres flottants
‘ABSO’	égalité des 2 nombres flottants à un epsilon près (eps) en comparaison absolue : vrai si \(\|x1-x2\| < eps\)
‘RELA’	égalité des 2 nombres flottants à un epsilon près (eps) en comparaison relative : vrai si \(\|x1-x2\| < eps * \|x1\|\)

Remarque: Est-ce que le tableau est vraiment la forme idéale pour fournir l’information ? Est-ce qu’une liste n’est pas tout aussi lisible ?

Cas particulier des critères d’égalité (ou de non égalité) pour des nombres « flottants » :

‘EGAL’ : égalité “exacte” des 2 nombres flottants
‘ABSO’ : égalité des 2 nombres flottants à un epsilon près (eps) en comparaison absolue : vrai si \(|x1-x2| < eps\)
‘RELA’ : égalité des 2 nombres flottants à un epsilon près (eps) en comparaison relative : vrai si \(|x1-x2| < eps * |x1|\)

avec :

- ‘EGAL’ : égalité “exacte” des 2 nombres flottants
- ‘ABSO’ : égalité des 2 nombres flottants à un epsilon près (eps) en comparaison absolue : vrai si :math:`|x1-x2| < eps`
- ‘RELA’ : égalité des 2 nombres flottants à un epsilon près (eps) en comparaison relative : vrai si :math:`|x1-x2| < eps * |x1|`