Documentation#

Tip

Check the utils repository for additional cases, scripts, geo files and meshes.

Build#

Setup#

To build the doc on your personal machine, you’ll need the following requirements:

  • Python v3.x

  • make

  • Sphinx v4.x

To install required system packages:

sudo apt-get install python3 build-essential

To install Sphinx globally:

pip install 'sphinx==7.*'

To install additional packages:

pip install sphinx-copybutton

and:

sudo apt-get install graphviz

Then, install the Sphinx requirements:

pip install -r doc/requirements.txt

Build HTML#

To build standalone HTML files like the CI would, enter the following commands:

cd doc
make html

The generated files should be in the build/html directory. Open index.html in a browser to view the rendered documents.

General Rules and Format#

Throughout the documentation, you may notice that the different pages follow a certain format to ensure uniformity and help users to navigate more fluidly. Here are the different elements that must be considered when contributing to the documentation of Lethe:

  • Titles and subtitles must be capitalized following the Chicago Manual of Style:

    • First and last words of the title/subtitle must be capitalized.

    • Capitalize:

      • adjectives (e.g., Small, Large)

      • adverbs (e.g., Warmly, Rapidly)

      • nouns (e.g., Ball, Cylinder)

      • pronouns (e.g., They, She, He)

      • subordinating conjunction when fewer than 5 letters (e.g., When, Once)

      • verbs (e.g., Melt, Create)

    • Do not capitalize:

      • articles (e.g., a, an, the)

      • coordinating conjunctions (e.g., and, but, for)

      • prepositions (e.g., at, by, to)

      • second word after a hyphenated prefix (e.g., Mid-, Non-) in compound modifiers (e.g., Mid-year, Non-linear)

      • words with less than four letters

    Tip

    If you are unsure of the capitalization of your title or subtitle, you can use online tools to help you out.

  • Examples generally contain the following subsections in the listed order:

    • Features lists features of the example.

    • Files Used in This Examples lists files used in the example in alphabetical order.

    • Description of the Case describes the system studied in the example.

    • Parameter File describes the different parameter subsections involved in the example. Each subsection of interest of the parameter file begins with its name as a sub-heading.

    • Running the Simulation displays the command used to run the example and gives an scale of the running duration.

    • Results or Results and Discussion displays results of the simulation and comments on them.

    • Possibility for Extension lists different interesting ways to extend the example.

    • References lists references used in the example in IEEE referencing style format.

      See also

      More information on the IEEE referencing style can be found in the IEEE Reference Guide.

      Here is an example of how references should appear in:

      • In-text citation:

        The Lethe: An open-source parallel high-order adaptative CFD solver for incompressible flows article by Blais et al. [1] is used as an example.

      • The References list:

        Following the format:

        [#AuthorYear] A. A. Author, “Name of the paper,” Abbreviated Title of the Journal, vol. x, no. x, pp. xxx-xxx, Abbreviated month, year, doi: xxx.

        The code in the documentation should be formatted as follows:

        .. [#blais2020] \B. Blais *et al.* “Lethe: An open-source parallel high-order adaptative CFD solver for incompressible flows,” *SoftwareX*, vol. 12, pp. 100579, Jul. 2020, doi: `10.1016/j.softx.2020.100579 <https://doi.org/10.1016/j.softx.2020.100579>`_.\"""

        Important

        When citing, the “et al.” notation is used in:

        • In-text citation if there are three or more authors for a given reference.

        • The References list if there are more than six authors for a given reference.

    Note

    These subheadings can take the singular or plural form depending on the example. Feel free to adapt them and add more layers to structure your own examples.

Equations#

Sphinx can render equations using the MathJax backend.

Examples#

.. math::
    i^2=-1

gives:

\[i^2=-1\]
.. math::
    df=\frac{\partial f}{\partial t}

gives:

\[df=\frac{\partial f}{\partial t}\]
.. math::
    \rho\left[\frac{\partial \bar{u}}{\partial t} + \bar{u}\cdot\bar{\nabla} \bar{u} \right] = - \bar{\nabla} \bar{p} + \mu \bar{\nabla}^2 \bar{u} + \rho \bar{g}

gives:

\[\rho\left[\frac{\partial \bar{u}}{\partial t} + \bar{u}\cdot\bar{\nabla} \bar{u} \right] = - \bar{\nabla} \bar{p} + \mu \bar{\nabla}^2 \bar{u} + \rho \bar{g}\]

Code#

Python syntax highlight:

.. code-block:: python
    your code

C++ syntax highlight:

.. code-block:: cpp
    your code

The code block in text mode is commonly used in the examples to show sections of a parameter file:

.. code-block:: text
    your code

Warning

Keep in mind the proper indentation of the sections of the parameter file. We recommend the use of the prmindent script located in the contrib/utilities folder before copying sections of a parameter file to the documentation. Do NOT use tabs in these blocks of code, as they will not be recognized, leading to the wrong indentation.

Examples#

.. code-block:: python
    for i in range(5):
    print(i)

gives:

for i in range(5):
print(i)

.. code-block:: cpp
    for (int i = 0 ; i<5 ; i++) {
        std::cout << i << std::endl;
    }

for (int i = 0 ; i<5 ; i++) {
    std::cout << i << std::endl;
}

Tables#

.. list-table::
    :header-rows: 1

    * - My
        - Beautiful
        - Table
    * - tables
        - are
        - rendered
    * - with
        - automatic
        - strip

Gives:

My

Beautiful

Table

tables

are

rendered

with

automatic

strip