.. _d8.00.01-directives: .. include:: ../../../../../_cache/math_styles.rst 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 :ref:`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 : .. code-block:: rst .. _d8.00.01-myfunction: .. code-block:: python :caption: Exemple de code Python def myfunction(x): """Example function.""" return x + 1 Ce qui donne : .. _d8.00.01-myfunction: .. code-block:: python :caption: 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 :ref:`d8.00.01-myfunction` ou le :numref:`d8.00.01-myfunction`. est obtenu avec : .. code-block:: rst Voir un exemple de :ref:`d8.00.01-myfunction` ou le :numref:`d8.00.01-myfunction`. .. _d8.00.01-equations: É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 : .. code-block:: rst Les équations :eq:`eq-chaleur` et :eq:`eq-fourier` sont extraites du document :ref:`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 :eq:`eq-chaleur` et :eq:`eq-fourier` sont extraites du document :ref:`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. 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. .. _d8.00.01-math-typo: 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: :math:`\boldsymbol{\sigma}` (avec ``\boldsymbol``) et :math:`\mathbf{\sigma}` (avec ``\mathbf``). Pour les (petites) déformations, le symbole ``\varepsilon`` (:math:`\varepsilon`) est plus conforme aux habitudes des mécaniciens que ``\epsilon`` (:math:`\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: .. code-block:: rst .. math:: \left \lbrace \begin{array}{ll} eq1 & \text { pour cette valeur} \\ eq2 & \text { pour l'autre valeur} \end{array} \right. Ce qui donne: .. math:: \left \lbrace \begin{array}{ll} eq1 & \text { pour cette valeur} \\ eq2 & \text { pour l'autre valeur} \end{array} \right. Les opérateurs mathématiques doivent être déclarés de la manière suivante .. code-block:: rst .. math:: \DeclareMathOperator{\dist}{dist} Ne pas écrire ``mathit{dist}`` par exemple. Comparez le résultat: .. math:: \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: .. math:: \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. Ces barres verticales permettent en particulier de désigner les normes : ``\Vert \underline{x} \Vert`` donne :math:`\Vert \underline{x} \Vert` ``\parallel \underline{x} \parallel`` donne :math:`\parallel \underline{x} \parallel` Et des valeurs absolues: ``\vert {x} \vert`` donne :math:`\vert {x} \vert` ``\mid {x} \mid`` donne :math:`\mid {x} \mid` .. _d8.00.01-math-styles: 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) : .. code-block:: rst .. include:: ../../../../../_cache/math_styles.rst On peut ainsi utiliser des notations normalisées pour : .. csv-table:: vecteur, :math:`\vector{u}`, ``\vector{u}`` matrice, :math:`\tensTwo{A}`, ``\tensTwo{A}`` norme euclidienne, :math:`\normEucl{\vector{v}}`, ``\normEucl{\vector{v}}`` Exemple : .. math:: :label: styles-example \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 . 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. .. _d8.00.01-figures: Figures ------- .. code-block:: rst .. 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 : .. figure:: ../../../man_r/r5/r5.03.01/images/Object_69.svg :name: d8.00.01-fig-newton :width: 30% 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. .. code-block:: rst Lien vers la figure :ref:`d8.00.01-fig-newton` ou :numref:`d8.00.01-fig-newton`. Ce qui donne : Lien vers la figure :ref:`d8.00.01-fig-newton` ou :numref:`d8.00.01-fig-newton`. 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 : .. image:: ../../../../_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 : .. image:: ../../../../_static-shared/logo-light.png :class: only-light .. image:: ../../../../_static-shared/logo-dark.png :class: only-dark 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) : .. image:: ../../../../_static-shared/logo-light.png :class: dark-light .. image:: ../../../../_static-shared/logo-dark.png :class: dark-light Listes à puces, numérotées -------------------------- Exemple : .. code-block:: rst * 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 : .. code-block:: rst #. 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 : .. code-block:: rst 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 : .. code-block:: rst .. _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 : .. _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 =========== ======== La présence du titre dans le tableau le numérote automatiquement. Pour y faire référence, on utilise : .. code-block:: rst Voir les :ref:`d8.00.01-tab-simp` ou :numref:`d8.00.01-tab-simp`. Ce qui donne : Voir les :ref:`d8.00.01-tab-simp` ou :numref:`d8.00.01-tab-simp`. Tableau csv ~~~~~~~~~~~ Dès que le tableau est plus compliqué, le format CSV est préférable : .. code-block:: rst .. 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 : .. 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" Tableaux en listes ~~~~~~~~~~~~~~~~~~ On peut aussi utiliser ce format utilisant deux niveaux de listes à puces : .. code-block:: rst .. 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 : .. 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