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.
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:
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:
:func:`tensorly.function` to refer a function:
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