.. _documentation: 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: .. code:: python 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 .. code:: rst :: block of code on several lines... Refer to functions or modules ----------------------------- In the documentation, you can refer to modules as :literal:`:mod:`tensorly.module``, for instance the tensor algebra module: :mod:`tensorly.tenalg`. Similarly, use :literal:`:func:`tensorly.function`` to refer a function: :func:`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