Writing documentation

Documentation is a crutial part of this library. Here, we cover some elements of syntax with Sphinx and reStructuredText (the .rst files), which is the format we use.

Docstrings

All functions and classes should come with useful docstrings. For these, we use the numpy style docstrings. For instance, for a function, we expect the following docstring:

def function(arg):
   """One line description

   Longer description,
   possibly in several lines

   Parameters
   ----------
   arg : type
      description

   Returns
   -------
   variable : type
      description

   Examples
   --------
   text
   >>> code
   expected result

   Notes
   -----
   Detailed explanation
   """
   pass

In particular, use single backticks for variable’s names: `variable`.

Double backticks are used for inline code: ``inline code``.

For blocks of code, use double colons, leave a white line and indent said lines of code

::

   block of code
   on
   several
   lines...

Refer to functions or modules

In the documentation, you can refer to modules as :mod:`tensorly.module`, for instance the tensor algebra module: tensorly.tenalg. Similarly, use :func:`tensorly.function` to refer a function: tensorly.base.unfold.

Titles

Titles are created by underlying them, and the hierarchy is automatically determined by Sphinx. If you do not want your title to appear in the table of contents, use a rubric:

.. rubric:: Title