\[\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{\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} \times #1 } \newcommand{\gradVector}[1]{\vector{\nabla} \times #1 } \DeclareMathOperator{\rand}{rand} \DeclareMathOperator{\round}{round} \DeclareMathOperator{\trace}{trace} \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{\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}\]

2. Content and layout#

2.1. Paragraphs#

In RST, paragraphs are simply blocks of text separated by a line break.

To facilitate proofreading and quickly visualize the changes made in a document, It is recommended not to write lines of more than a hundred characters. However, the automatic conversion of documents from the ODT format did not respect this instruction.

Avoid putting « in code_aster » or « in aster » in documentation. We can well imagine that it is in code_aster, since we are in the code_aster documentation! In this regard, Christophe- MMN .Durand case law, we say « code_aster » not « LE code_aster »).

The « document versions » tables (in particular in the R docs) are removed. The history of the versions is naturally supported by the Git repository system. It is therefore useless to complete this table which will be deleted when the documents are validated.

As much as possible, avoid putting data entry extracts into the documentation. Indeed, these snippets are not modified if the syntax evolves and they become syntactically incorrect. Data inputs are put into test cases.

For numeric values, always put a number after the decimal point (1.0 and not 1.) because 1. refers to the start of a numbered list.

2.2. Formatting#

The purpose of RST is precisely to do a minimum of formatting to keep documentation homogeneous and legible even in plain text. The RST file itself can be read.

Use:

  • an asterisk: *text* for an text in italics,

  • two asterisks: **text** for bold text,

  • serious accents: ``text`` for a snippet of code.

Formatting using html code is not allowed.

note

You write keywords normally: MODELE. It is not necessary to write « MODELE ».

The command paragraph is généré automatiquement. In the command documentation, do not repeat the syntax in the description of each keyword. It’s redundant and sometimes a step up to date.

For code blocks, we use:

.. _d8.00.01-myfunction:

.. code-block: python
    :caption: Python code example

    def myfunction (x):
        "" "Example function" ""
        Return x + 1

This results in:

Code source 2.1 Python code example#
   def myfunction (x):
       "" "Example function" ""
       Return x + 1

You can use « :caption:``. The legend is then displayed, the block is numbered and you can thus refer to it by displaying this number.

See an example of Python code example or Code source 2.1.

is obtained with:

See an example of :ref:`d8.00.01-myfunction` or :numref:`d8.00.01-myfunction`.

2.3. Equations#

The equations are entered in LaTeX format.

There are a lot of online editors:

< https://fr.overleaf.com/learn>* The LaTeX documentation provided by `Overleaf`_ is one of

more complete

< http://detexify.kirelabs.org/classify.html>* The `Detexify`_ site is very practical:

You draw your symbol with the mouse and it finds you the LaTeX command Correspondent

Equations can be separated or*inline* in the text.

The heat equation is:

Equations :eq:`eq-chaleur` and :eq:`eq-fourier` are taken from
document :ref:`r5.02.01 <r5.02.01>`:

.. _d8.00.01-eq-heat:

.. math:
    :label: eq-heat

    -\ text {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)

with :math:`\lambda` the thermal conductivity, :math:`\rho {C}_{p}` the heat
volume at constant pressure.

This results in:

Equations eq-chaleur and (2.2) are taken from document r5.02.01:

\[\]

: label: eq-heat

-text {div} (-lambdanabla 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)\]

with \(\lambda\) the thermal conductivity, \(\rho {C}_{p}\) the heat volume at constant pressure.

It is useful to add the reference « .. _d8.00.01-eq-heat: « to insert a link to an equation from another page or document.

2.4. General rules for the typography of equations#

LaTeX is not a WYSIWYG editor, the fundamental concept (like RST) is to separate the background from the shape. So don’t do manual formatting (adding spaces, returning to the line, etc.).

It is certain that RST and the HTML generator include theamsmath``` packages and their cousins. These packages were developed by the American Mathematical Society, which gives access to « standardized » characters and methods in the community (including French ones).

It is not necessary to number all the equations.

Giving font formatting guidelines should be avoided. For example, « mathbim {=} » is useless.

If you need text in an equation, use the « text {tagada} » environment. It is important for the management of spaces (note the presence of spaces) and characters accented.

To add spaces to an equation (in increasing order of spacing): « , », « quad » and \ quad. Avoid unbreakable spaces in math mode (like ~) it constrains the algorithm too much LaTeX rendering. The formatting guidelines in math mode are in the form of environments dedicated (array for example).

Get in the habit of using « lbracerbrace`` or »left (andright) « , so the height of brackets may be adjusted if you change the content. Do not use / for division, but « frac ». For example, « frac {1} {3} » rather than 1/3.

For Greek letters (and mathematical symbols in general) in bold, « mathbf {sigma} » ne won’t work, you have to « boldsymbol {sigma} ».

Compare: \(\boldsymbol{\sigma}\) (with « boldsymbol ») and \(\mathbf{\sigma}\) (with »boldsymbol ») mathbf).

For (small) deformations, the « varepsilon » symbol (\(\varepsilon\)) is more consistent to the habits of mechanics as « epsilon » (\(\epsilon\)).

the « cdot » directive is for the dot product only, don’t use it outside of this specific context. Likewise, it is recommended not to put . (multiplicative point) between scalars for example, if you want it to be cleaner (especially between letters) Greek characters (which are in italics), you can insert a space like « , ».

To write a set of equations, here is an example of syntax:

.. math:
    \ left\ {\ begin {array} {ll}
    eq1 &\ text {for this value}\\
    eq2 &\ text {for the other value}
    \ end {array}\ right.

This results in:

\[\]
left{begin {array} {ll}

eq1 &text {for this value}\ eq2 &text {for the other value} end {array}right.

Mathematical operators should be declared as follows:

.. math:
    \ declaremaThoperator {\ dist} {dist}

For example, don’t write ``mathit {dist} « . Compare the result:

\[\]
declareMathOperator {dist} {dist}

disttext {with operator declaration}mathit {dist}text {with dedicated formatting}

The vertical bars are defined by « green » and »Green », do not use « parallel » and ``mid ». Compare the result:

\[\]
left{begin {array} {ll}

text {Vertical barmid:}mid &text {Vertical bargreen:}green\ text {Double vertical barparallel:}parallel &text {Double vertical barGreen:}Green\ end {array}right.

In particular, these vertical bars make it possible to designate the standards:

« Greenunderline {x}Green`` gives \(\Vert \underline{x} \Vert\) \ parallel\ underline {x}\ parallel results in \(\parallel \underline{x} \parallel\)

And absolute values:

« green {x}green`` gives \(\vert {x} \vert\) « mid {x}mid`` gives \(\mid {x} \mid\)

2.5. Equation style sheet#

It is recommended to use the equation style sheet, which groups the notations together. the most frequent in mechanics, which makes it possible to have a certain homogeneity in the documentation.

To do this, include RST at the top of each file (on the 2nd line just after the main reference for example):

.. include:../../../../../../.. /_cache/math_styles.rest

Thus, standardized notations can be used to:

vector

\(\vector{u}\)

vector {u}

matrix

\(\tensTwo{A}\)

TensTwo {A}

Euclidean norm

\(\normEucl{\vector{v}}\)

normeUCL {vector {v}}

Example:

(2.3)#\[\begin{split} \ left\ lbrace\ begin {array} {ll} & -\ vector {div}\ left (\ TensTwo {P}\ right) =\ underline {f} &\ text {in}\\,\,\ Omega\\ &\ vector {u} =\ vector {u} _d &\ text {on}\,\ gamma_ {D}\\ &\ tensTwo {P}\,\ vector {N} =\ vector {N} =\ vector {t} _ {N} &\ text {on}\\\\\\\ & P_ {n}\ le 0,\, g_ {n} (\ vector {u})\ ge 0,\, g_ {n} (\ vector {u})\, P_ {n} =0 &\ text {n} =0 &\ text {on}\ text {on}\,\ Gamma_ {u})\ &\normeUCL {\ vector {P} _ {\ tau}}\ le 0\ text {si}\ vector {v} _ {\ tau} _ {\ tau} = \ vector {0}\ text {and}\ vector {P_ {\ tau}} = -s\ frac {\ vector {v} _ {\ tau}} {\normeUCL {\ vector {v} _ {\ tau} _ {\ tau}}}}} &\ text {\ tau}}}} &\ text {on}\,\ gamma_ {C}\\ \ end {array}\ right.\end{split}\]
Important

Do not modify this style file on your own initiative, if you want to enrich it or change it, ask the person responsible for the reference documentation.

2.6. Figures#

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

    Newton diagram

This results in:

_images/Object_69.svg

The figure directive allows you to define a « Newton diagram » legend, contrary to the image directive. The option « :name:`` defines a reference that is typically used.

Link to figure :ref:`d8.00.01-fig-newton` or :numref:`d8.00.01-fig-newton`.

This results in:

Link to figure d8.00.01-fig-newton or d8.00.01-fig-newton.

2.6.1. Image adapted to the light/dark theme#

By default, the image is automatically adjusted to best fit the theme. A white background is added and the brightness is reduced:

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

You can choose one image for the light background and one for the dark background using the :class: only-light or :class: only-dark attribute. We display one or the other of the images according to the theme:

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

: class: only-light

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

: class: only-dark

If we consider that the image should be displayed as it is, without adjustment, Whatever the theme, we use :class: dark-light (these are the two previous images without adjustment):

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

2.7. Bulleted lists, numbered#

Example:

* A first element
* A second

  * With a sub-level

* The third and final element.

This results in:

  • A first element

  • A second

    • With a sub-level

  • The third and final element.

With automatic numbering:

#. A first element
#. A second
#. The third and final item.

This results in:

  1. A first element

  2. A second

  3. The third and final item.

2.8. notes#

To add a remark, simply do:

note
    It is necessary to specify this or that.

This results in:

note

It is necessary to specify this or that.

2.9. Different types of tables#

2.9.1. Simple chart#

For small tables, you can use the simplest form:

.. _d8.00.01-tab-simp:

.. table:: Material parameters of steel
   :widths: auto

   ===== ===== =====
    Parameter Value
   ===== ===== =====
   E 2.1e9
   :math:`\nu` 0.3
   ===== ===== =====

This results in:

The presence of the title in the table automatically numbers it. To refer to it, we use:

See :ref:`d8.00.01-tab-simp` or :numref:`d8.00.01-tab-simp`.

This results in:

See d8.00.01-tab-simp or d8.00.01-tab-simp.

2.9.2. CSV table#

As soon as the table is more complicated, the CSV format is preferred:

.. csv-table:: Material parameters of steel
    :header: "Parameter", "Value"
    :widths: 50, 50

    E, 2.1e9
    :math:`\nu`, 0.3
    ":math:`\lambda`, :math:`\mu` ", "being 'known' as :math:`\frac{E \nu}{(1+\nu)(1-2\nu)}`,
    That is 1.21e9

    and :math:`\frac{E}{2(1+\nu)}`, which is 0.81e9"
Note

Double quotes `` »``allow you to delimit the content of columns (mandatory) when a comma is in the content of the cell).

You can go back the line (between ") and skip a line to start a new paragraph.

This results in:

Tableau 2.1 Paramètres matériaux de l’acier#

Parameter

Value
widths:

50

50

E

2.1e9

\(\nu\)

0.3

\(\lambda\), \(\mu\)
being “known” as \(\frac{E \nu}{(1+\nu)(1-2\nu)}\),

That is 1.21e9

and \(\frac{E}{2(1+\nu)}\), which is 0.81e9

2.9.3. Tables in lists#

You can also use this format using two levels of bulleted lists:

.. list-table:: Material parameters of steel
    :widths: 50, 50
    :header-rows: 1

    * - Parameter
      - Value
    * - E
      - 2.1e9
    * - :math:`\nu`
      - 0.3
    * - :math:`\lambda`, :math:`\mu`
      - being 'known' as :math:`\frac{E \nu}{(1+\nu)(1-2\nu)}`,
        That is 1.21e9

        and :math:`\frac{E}{2(1+\nu)}`, which is 0.81e9

This results in:

: widths: 50, 50
header-rows:

1

    • Parameter

    • Value

    • E

    • 2.1e9

    • \(\nu\)

    • 0.3

    • \(\lambda\), \(\mu\)

    • being “known” as \(\frac{E \nu}{(1+\nu)(1-2\nu)}\), That is 1.21e9

      and \(\frac{E}{2(1+\nu)}\), which is 0.81e9