1. Sections and hyperlinks#

1.1. Header page#

A document is identified as its documentary key. This key must be provided by the documentation manager.

This key should also be the name of the directory for this document in source/manuals/man_x/x0/x0/x0.00.00 where x is a, r, d, u, v, v, m, or s for salome_meca.

The main page should be named index.rst in this directory.

This page should contain:

the reference to the document: « .. _x0.00.00: « ,
the title of the document, starting with **x0.00.00** (used for the global menu),
the subject/summary of the document,
the table of contents giving access to the various pages of the document.

Example of index.rst:

.. _r5.03.01:

**r5.03.01** Quasi-static nonlinear algorithm (STAT_NON_LINE)
===== ===== =====

**Summary:**

The STAT_NON_LINE [:external:ref:`u4.51.03 <u4.51.03>`] operator allows...

etc.

.. toctree:
    :hidden:

    Self

.. toctree:
    :maxdepth: 2
    :numbered:

    Presentation
    Newton_method

Commands: For instructions for using the commands (u4 and u7), the title of the document must have this format in order to automatically extract the list of commands:
Test cases: Similarly, for test case validation notes, the title format is imposed in order to build the list of test cases:

1.2. Section levels#

Section titles are defined by underlining or framing them with characters. specials.

Page title
===== =====

It is the equivalent of a*Level 1* title.

Section title
----------------

It is the equivalent of a*Level 2* title.

Sub-section title
~~~~~~~~~~~~~~~~~~~~~~~

It is the equivalent of a*Level 3* Title.

Framing can also be used:

===== =====
Page title
===== =====

1.3. Hypertext links#

1.3.1. To the sections of a document#

The reference must be defined just before the section:

.. _r5.03.01-prediction-euler:

Euler prediction phase
---------------------------

Note

In order to avoid collisions between the references of the various documents,

It is proposed to systematically put the key of the document as a prefix. Do not put « .. _bibliography: « but ».. _r5.03.01-bibliography: « .

Prefer hyphens « - » to the underscore « _ » to separate elements, the latter having a particular meaning depending on the context.

Then refer to it with the « :ref:`` » directive:

This creates a link to section :ref:`d8.00.01-liens`.
See section :ref:`r5.03.01-prediction-euler` in another document
or, consult document :ref:`r5.03.01 <r5.03.01>`.

This results in:

This provides a link to section Hypertext links within this document. See section r5.03.01-prediction-euler in another document… or, consult document r5.03.01.

You can also use :external :ref: to reference another document but it is not necessary.

notes

There is no need to add a reference before each section. We only do it when we need it.

Avoid using links RST ``Section levels`_ which are more complicated to be maintained. You have to change the link AND the references as soon as you change the section, there is more risk of conflicts…

1.3.2. Links to the equations#

See paragraph Equations for the definition of equations.

Note

There is no global numbering of the equations.

For example:

(1.1)#\[e^ {i\ pi} + 1 = 0\]

We insert a link to this equation with « (1.1) », which gives (1.1). The format is « <numéro de section>. <equation number in the section>``.

To refer to an equation from a different page and, even more so, from another document, you can add a label:

If eq-chaleur is ambiguous, l’équation de la chaleur will be preferred.

1.3.3. Links to the figures#

See paragraph Figures for an illustration of d8.00.01-fig-newton or from figure d8.00.01-fig-newton.

1.3.4. Links to bibliographical references#

We use Sphinx*quotes* in this way:

We can mention [bib2] _ or [bib2] _.

This results in:

We can mention [bib2] _ or [bib2] _.

See paragraph Bibliography for the list of references.