\[\newcommand{\vector}[1]{\underline{#1}} \newcommand{\vectorZero}{\vector{0}} \newcommand{\tensTwo}[1]{\boldsymbol{#1}} \newcommand{\tensTwoZero}{\tensTwo{0}} \newcommand{\tensTwoUnit}{\tensTwo{I}} \newcommand{\tensFour}[1]{\mathbb{#1}} \newcommand{\inverse}[1]{{#1}^{-1}} \newcommand{\transpose}[1]{{#1}^{T}} \newcommand{\inverseTranspose}[1]{ {#1}^{-T}} \newcommand{\vectorCmp}[2]{#1_{\left(#2\right)}} \newcommand{\vectorCmpCO}[2]{#1_{\left(#2\right)}} \newcommand{\vectorCmpCT}[2]{#1^{\left(#2\right)}} \newcommand{\tensTwoCmpCO}[3]{#1_{\left(#2 #3\right)}} \newcommand{\tensTwoCmpCT}[3]{#1^{\left(#2 #3\right)}} \newcommand{\tensTwoInva}[2]{I^{#1}_{#2}} \newcommand{\tensTwoDevia}[1]{\boldsymbol{\tilde{#1}}} \newcommand{\tensFourCmpCO}[5]{#1_{\left(#2 #3 #4 #5\right)}} \newcommand{\tensFourCmpCT}[5]{#1^{\left(#2 #3 #4 #5\right)}} \newcommand{\domain}{\Omega} \newcommand{\domainRefe}{\domain^{0}} \newcommand{\domainCurr}{\domain^{t}} \newcommand{\bound}{\partial\domain} \newcommand{\boundRefe}{\bound^{0}} \newcommand{\boundCurr}{\bound^{t}} \newcommand{\boundN}{\bound_{\textrm{N}}} \newcommand{\boundNRefe}{\boundN^{0}} \newcommand{\boundNCurr}{\boundN^{t}} \newcommand{\boundD}{\bound_{\textrm{D}}} \newcommand{\boundDRefe}{\boundD^{0}} \newcommand{\boundDCurr}{\boundD^{t}} \newcommand{\normal}{\vector{n}} \newcommand{\normalRefe}{\normal^{0}} \newcommand{\normalCurr}{\normal^{t}} \newcommand{\posi}{\vector{x}} \newcommand{\posiRefe}{\posi^{0}} \newcommand{\posiCurr}{\posi^{t}} \newcommand{\disp}{\vector{u}} \newcommand{\dispVirt}{\delta\vector{v}} \newcommand{\funcTransfor}{\vector{\varphi}^{t}} \newcommand{\gradTransfor}{\tensTwo{F}} \newcommand{\jacobTransfor}{J} \newcommand{\posiIncr}{\vector{dx}} \newcommand{\posiIncrRefe}{\posiIncr^{0}} \newcommand{\posiIncrCurr}{\posiIncr^{t}} \newcommand{\strainCmp}{\varepsilon} \newcommand{\strain}{\tensTwo{\strainCmp}} \newcommand{\EGLCmp}{E} \newcommand{\ECGDroiteCmp}{C} \newcommand{\ECGGaucheCmp}{B} \newcommand{\ELOGCmp}{{E}_{ln}} \newcommand{\EGL}{\tensTwo{\EGLCmp}} \newcommand{\ECGDroite}{\tensTwo{\ECGDroiteCmp}} \newcommand{\ECGGauche}{\tensTwo{\ECGGaucheCmp}} \newcommand{\ELOG}{\tensTwo{\ELOGCmp}} \newcommand{\EDilCmp}{C^{\star}} \newcommand{\EDil}{\tensTwo{\EDilCmp}} \newcommand{\divTensTwo}[1]{\vector{\nabla} {\cdot} #1 } \newcommand{\divVector}[1]{\vector{\nabla} {\cdot} #1 } \newcommand{\gradScal}[1]{\vector{\nabla} #1 } \newcommand{\gradVector}[1]{\vector{\nabla} \times #1 } \DeclareMathOperator{\rand}{rand} \DeclareMathOperator{\round}{round} \DeclareMathOperator{\trace}{trace} \DeclareMathOperator{\rank}{rang} \DeclareMathOperator{\dev}{dev} \DeclareMathOperator{\cot}{cot} \newcommand{\metric} {\tensTwo{g}} \newcommand{\vectorBaseCV}[1]{\vector{g_{#1}}} \newcommand{\vectorBaseCT}[1]{\vector{g^{#1}}} \newcommand{\metricRefe} {\metric^{t}} \newcommand{\metricCurr} {\metric^{0}} \newcommand{\discVect}[1]{\lbrace #1 \rbrace} \newcommand{\discVectLigne}[1]{\langle #1 \rangle} \newcommand{\discVectZero}{\discVect{0}} \newcommand{\discVectCmp}[2]{\lbrace #1 \rbrace_{(#2)}} \newcommand{\discVectLigneCmp}[2]{\langle #1 \rangle_{(#2)}} \newcommand{\discMatr}[1]{\left[ #1 \right]} \newcommand{\discMatrZero}{\discMatr{0}} \newcommand{\discMatrCmp}[3]{\left[ #1 \right]_{(#2#3)}} \newcommand{\onQuadPoint}[2]{{#1}_{#2}} \newcommand{\onNode}[2]{{#1}^{#2}} \newcommand{\quadOrder}{k_{Q}} \newcommand{\nbQuadPoint}{n_Q} \newcommand{\quadWeight}[1]{\omega_{#1}} \newcommand{\quadPointIndex}{i_{\textrm{pg}}} \newcommand{\nodeIndex}{i_{\textrm{no}}} \newcommand{\pres}{p} \newcommand{\presRefe}{\pres^{0}} \newcommand{\presCurr}{\pres^{t}} \newcommand{\stressCmp}{\sigma} \newcommand{\stress}{\tensTwo{\stressCmp}} \newcommand{\stressPKTwoCmp}{S} \newcommand{\stressPKTwo}{\tensTwo{\stressPKTwoCmp}} \newcommand{\work}[1]{W^{#1}} \newcommand{\enerInterne}{\Psi_i} \newcommand{\yieldStress}{\sigmaCmp_{Y}} \newcommand{\youngModulus}{E} \newcommand{\youngModulusCplx}{E^{\star}} \newcommand{\poissonCoef}{\nu} \newcommand{\poissonCoefCplx}{\nu^{\star}} \newcommand{\shearModulus}{G} \newcommand{\bulkModulus}{K} \newcommand{\modulusTangent}{\tensFour{K}} \newcommand{\anglDila}{\psi} \newcommand{\anglFric}{\varphi} \newcommand{\cohesion}{c} \newcommand{\presCapi}{\pres_{c}} \newcommand{\presEau}{\pres_{w}} \newcommand{\presAir}{\pres_{a}} \newcommand{\shapeFunc}{\Phi} \newcommand{\shapeDFunc}{B} \newcommand{\measLine}{\, \mathrm{d} l} \newcommand{\measDomain}{\, \mathrm{d} \domain} \newcommand{\measBound}{\, \mathrm{d} \Gamma} \newcommand{\normEucl}[1]{\Vert{#1} \Vert } \newcommand{\valeAbs}[1]{\vert{#1} \vert } \newcommand{\derivee}[2]{#1_{, #2}} \newcommand{\soundSpeed}{c} \newcommand{\soundSpeedComp}{c_{P}} \newcommand{\soundSpeedCisa}{c_{S}} \newcommand{\posiTang}{\posi_{\tau}} \newcommand{\posiNorm}{{x}_{n}} \newcommand{\dispTang}{\disp_{\tau}} \newcommand{\dispNorm}{{u}_{n}} \newcommand{\basisVector}[1]{\vector{e}_{#1}} \newcommand{\sigmVector}{\vector{t}} \newcommand{\sigmVectorTang}{\sigmVector_{\tau}} \newcommand{\sigmVectorNorm}{t_{n}} \newcommand{\lameLambda}{\lambda} \newcommand{\lameMu}{\mu} \newcommand{\temp}{T} \newcommand{\therCp}{C_{p}} \newcommand{\therFlux}{\vector{q}} \newcommand{\therCondTher}{\lambda} \newcommand{\therSource}{s} \newcommand{\tempVirt}{\delta T} \newcommand{\beamArea}{S} \newcommand{\beamLength}{L} \newcommand{\setC}{\mathbb{C}} \newcommand{\setR}{\mathbb{R}}\]

2. Contenu et mise en forme#

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

2.2. 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 2.1 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 2.1.

est obtenu avec :

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

2.3. É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 (2.1) et (2.2) sont extraites du document r5.02.01 :

(2.1)#\[-div(-\lambda \nabla T(r,t)) + s(r,t) = \rho {C}_{p} \frac{\partial T(r,t)}{\partial t}\]
(2.2)#\[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.

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

2.5. 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 :

(2.3)#\[\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.

2.6. 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. 2.1 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 Schéma de Newton ou Fig. 2.1.

2.6.1. 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 :

../../../../_static-shared/logo-light.png

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 :

../../../../_static-shared/logo-light.png ../../../../_static-shared/logo-dark.png

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

../../../../_static-shared/logo-light.png ../../../../_static-shared/logo-dark.png

2.7. 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 :

  1. Un premier élément

  2. Un deuxième

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

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

2.9. Différents types de tableaux#

2.9.1. 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 2.1 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 2.1.

2.9.2. 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 2.2 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

2.9.3. 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 2.3 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