Writing documentation

Introduction

The documentation is written in reStructuredText using the Sphinx Documentation Generator.

The theme is based on ReadTheDocs Sphinx Theme with a few modifications.

See the Sphinx Documentation for details.

Getting started

Documenting functions and arguments

Documentation of functions arguments is using the Google Style supported by the sphinx-ext-napoleon extension.

This style is used in C++/Python bindings, for example, see the documentation of code_aster.Objects.Formula.evaluate() which is generated from the source file FormulaInterface.cxx:

        .def( "evaluate", &FormulaClass::evaluate, R"(
Evaluate the formula with the given variables values.

Arguments:
    val (list[float]): List of the values of the variables.

Returns:
    float/complex: Value of the formula for these values.
        )",
            ( py::arg( "self" ), py::arg( "*val" ) ) )

As an example for pure Python function, this description of my_function():

help_doc.my_function(arg1, arg2)

What the function does.

May add more detailed informations. Add a new line to start a new paragraph. Do not write lines longer than 80 chars following the PEP8 recommendation.

Example of a reference to internal objects code_aster.Objects.Mesh with it full name or Mesh with its basename.

Parameters:

• arg1 (int) – A description of the argument. If needed, it may be written on several lines that must be indented before next argument.

• arg2 (list[str]) – List of strings for the second argument.

Returns:

This function returns a dict object. There is always only one result, eventually it’s a tuple. That’s why the continued lines are not indented here.

Return type:

dict

is automatically generated from this source file:

def my_function(arg1, arg2):
    """What the function does.

    May add more detailed informations. Add a new line to start a
    new paragraph. Do not write lines longer than 80 chars following the
    `PEP8`_ recommendation.

    Example of a reference to internal objects
    :py:class:`code_aster.Objects.Mesh` with it full name or
    :py:class:`~code_aster.Objects.Mesh` with its *basename*.

    .. _PEP8: https://www.python.org/dev/peps/pep-0008/

    Arguments:
        arg1 (int): A description of the argument. If needed, it may be
            written on several lines that must be indented before next
            argument.
        arg2 (list[str]): List of strings for the second argument.

    Returns:
        dict: This function returns a *dict* object.
        There is always only one result, eventually it's a tuple. That's
        why the continued lines are not indented here.
     """
    return dict(a=arg1 + len(arg2))

Automatically generated pages

All source pages under Objects / DataStructures are automatically generated, except the page Pure Python extensions for DataStructure. These pages present all objects defined from code_aster.Objects by subclasses of DataStructure and the other types.

These pages are automatically generated by the script doc/scripts/generate_rst.py. It is similar to sphinx-apidoc by sorting and filtering objects in categories.

Providing a Continous Deployment of the documentation on ReadTheDocs would require to install all the code_aster prerequisites to entirely build libaster.so from scratch. That’s why the source tree also provides the script named doc/scripts/build_pylibaster.py. It extends the pydoc possibilities with a “Python renderer”. It allows to export a libaster.py module with the classes and functions from libaster.so with the signatures and docstrings only.

These scripts are executed by ./waf doc and write the automatically generated files into the source tree at doc/_automatic_.

Link to DataStructure

The previous example shows how to add a hyperlink to a DataStructure (here Mesh).

Please use links by refering to the code_aster.Objects package like this:

:py:class:`code_aster.Objects.Mesh`

and not:

:py:class:`libaster.Mesh`

The objects are the same but the documentation of code_aster.Objects.Mesh exists but not that of libaster.Mesh.

Note

Please always use links to DataStructures, Classes or Methods in the docstrings to improve the navigation in the documentation.

Link to functions

Use the same pattern to add a link to a function. Remember to use the full/native path to generate the hyperlink:

:py:func:`~code_aster.Supervis.Serializer.saveObjects`

and not:

:py:func:`code_aster.saveObjects`

even if saveObjects() is imported at the toplevel of the package.

Link to documentation paragraphs

When it is possible, prefer link to Python objects (see previous paragraph). Please use ref Sphinx role to add an internal link to another part of the documentation, and not the reStructuredText notation which is more difficult to maintain.

Label names used for cross-referencing must be unique. The convention is the code_aster documentation is: part-file[-section]. For example, if one needs to add a link to this paragraph, just add before this paragraph:

.. _devguide-documentation-link_to_paragraph:

and insert a link with:

:ref:`devguide-documentation-link_to_paragraph`

that is rendered with Link to documentation paragraphs.

Add an equation

Todo

Adding equations needs more requirements (dvipng for example).

Insert an image

This image

is inserted with :

.. image:: ../img/code_aster_200.png
    :align: center

Conventions

reStructuredText uses markers to define the section structure. Even the symbols used may change from one source file to another.

Please respect this convention to keep consistency between documents:

#######
Section
#######

*******
Title 1
*******

=======
Title 2
=======

Title 3
-------

Title 4
~~~~~~~

Generating the documentation

Configuration

Sphinx installation and requirements are checked during ./waf configure.

You need at least: sphinx-build, dot and convert.

Note

The documentation is only built with the MPI configuration.

Generation of html documents

To automatically extract the documentation from the Python objects, Sphinx imports the objects themself. That means that libaster is imported, and so, it must have been compiled. That’s why you must build code_aster before generating its documentation.

First step ./waf install, and then ./waf doc.

The html documentation is installed into <install-dir>/share/doc/html.

Note

It is necessary to remove the build/{debug,release}/doc directory to reflect last changes to update the List of TODOs page.

Browse the documentation

Just open the index.html from the installation directory:

firefox ../install/mpi/share/doc/html/index.html

Resources

• Sphinx Documentation Content.

• reStructuredText - Official site.

• reStructuredText Primer (Sphinx documentation).