.. _users_guide_conventions:

Users Guide Conventions & Writing Entries
=========================================

Conventions and policies for our `online docs
<https://www.discretization.de/pyddg/doc/>`_

(our docs = users guide + API docs)

- The users guide consists of the .rst files in ``pyddg\docs\source\...``
- When working on the users guide, you can build it from your local repository, as
  explained on the page :ref:`creating_docs`.

.. contents:: Table of contents
   :local:
   :backlinks: none

General Users Guide Policies
----------------------------

- Every code block should be a doctest.
- If a **new** feature has been added or the usage of an existing one has **changed**,
  the developer should write a short entry / adjust the corresponding existing entry in
  the **users guide**. The entry should contain a small, working **example** as a
  doctest. This is a non-optional requirement for a merge request.

Sections
~~~~~~~~

Generally, the user's guide follows a similar structure as the library itself. There are
two special sections:

- ``/docs/source/developers/`` contains documentation that is only relevant to
  developers.
- ``/docs/source/mathematics/`` contains explanations of mathematical background that
  are too long for a docstring or other, more general math background (hopefully with
  references). These pages should be linked to from docstrings using `Links to other
  sections in docs`_.

Document indices
~~~~~~~~~~~~~~~~

All ``.rst`` documents must be included in some ``.. toctree::`` list, otherwise they will not be reachable. Sphinx will automatically detect this and will complain when trying to build the docs.

We always set the option ``:titlesonly:`` on our toctrees, which means that only the main titles of documents should be included, as opposed to subheadings within the documents. This makes it more predictable where clicking a link will take you. For navigation within a document, a :ref:`local table of contents <localtocs>` should be used.

Write an Entry
--------------

- Write your article and put it in ``/docs/source/...``, for example as
  ``/docs/source/mathematics/your_article.rst``.
- Add it to the index at ``/docs/source/mathematics/index.rst``.

Syntax
~~~~~~

The syntax of ``.rst`` files can be very daunting at first. Here are some
references which may help you.

- `Sphinx Tutorial <https://sphinx-tutorial.readthedocs.io/step-1/>`_
- `RST Quick Reference <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_
- `RST & Sphinx Reference
  <https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/CodingGuidelines/CglRest/Index.html#restructuredtext-rest>`_

RST Converter
~~~~~~~~~~~~~

If you need to convert one markup format to another, you can use `pandoc <https://pandoc.org/>`_, which allows you to
convert pretty much any given markup format to another one. In case you only need to convert from ``.md`` to ``.rst``,
then `m2r <https://github.com/miyakogi/m2r>`_ might be useful to you.

.. _localtocs:

Tables of contents
~~~~~~~~~~~~~~~~~~

If an article has multiple subheadings and is sufficiently long (rule of thumb: It requires a significant amount of scrolling), it should include a table of contents (TOC). Use the following directive:

.. code-block:: rst

    .. contents:: Optional caption
        :local:
        :backlinks: none

There are two styles regarding the placement of the TOC in the document:

- If there **is** an introductory paragraph directly following the top-level heading, put the TOC after the introductory paragraph with the caption "Table of contents".
- If there **is no** introductory paragraph, i.e. the top-level heading is directly followed by a subheading, put the TOC between these two headings without a caption.

Embedding Images
----------------

It is often a good idea to render some pictures that can be included in the documentation. Python scripts that produce pictures for the documentation should be saved to ``/examples/blender/docs/``. The scripts in this folder are tested automatically.

Pictures are saved in the same directory as their files. You can include images using:

.. code-block:: rst

    .. image:: image.png
        :width: 500px
        :scale: 80 %
        :align: center

Consult the `sphinx docs <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images>`_ for more detail.

Emdedding GIFs
~~~~~~~~~~~~~~

If you want to embed GIFs, use **50 fps** (highest frame rate compatible with most modern browsers).

Links and Reference
-------------------

Links into the Library
~~~~~~~~~~~~~~~~~~~~~~

When referring to methods/classes of pyddg, you can create a
`link <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain>`_
to them through the corresponding **API docs** entry.

.. code-block:: rst

    :py:meth:`ddg.path.to.MyClass.method`.

Will result in a link with the name **'ddg.path.to.MyClass.method()'**, and

.. code-block:: rst

    :py:meth:`~ddg.path.to.MyClass.method`.

will result in a link with the name **'method()'**.

.. _links_to_other_sections_in_docs:

Links to other sections in docs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To link to a sub-headline within the same file, use the headline title in backticks and
add an underscore:

.. code-block:: rst

    `Headline Title`_

To link a section in a different file, set a unique marker like so:

.. code-block:: rst

    .. _headline_title:

    Headline Title
    --------------

And link to it anywhere like this:

.. code-block:: rst

    :ref:`headline_title`

or to get custom link text:

.. code-block:: rst

    :ref:`Click me! <headline_title>`

**Note:** There is a sphinx extension called ``autosectionlabel`` which allows
``:ref:``-style links across files using just headings without having to set markers.
However this requires all headings in the documentation to be unique, which is not the case
in ours. We could enable it with limited heading depth and a few edits and get around
it, but chose to disable it for now.

Maths
-----

In the users guide, mathematical equations should be written in **latex**:

.. code-block:: rst

    The new edge length are calculated as follows

    .. math:: \ell_{lk} = \sqrt{b^2 + c^2 -2bc\cos(\alpha + \delta)}.

Or in **inline mode**:

.. code-block:: rst

    The Delaunay property is checked via the cotan weights
    :math:`w_{ij} = \cot(\alpha^k_{ij}) + \cot(\alpha^l_{ij})`
    for an edge eij with adjacent triangles :math: `ijk` and :math: `ilj`.

- for **correct appearance** in the html documentation file:

  - use **raw strings** marked by the string prefix *r* or *R* or use **double
    backslashes** for LaTeX symbols
  - Always use a blank line before the math directive ``.. math::``.
  - For more details see `String and Bytes literals
    <https://docs.python.org/3.7/reference/lexical_analysis.html?highlight=string%20literals#string-and-bytes-literals>`_.

Doctests
--------
Everything in :doc:`../testing/doctests` also applies to doctests in the user's guide.

Additionally, the ``..literalinclude::`` directive supports embedding Python source code taken from actual Python modules and scripts.

Including code snippets from source files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Create a separate source file, e.g. ``example.py`` that can be run as a separate script. This script should go somewhere in the directory ``/examples/blender/docs/``. The test suite will automatically discover files in this directory and run them as part of the blender tests.
- Include parts of this file in your ``.rst`` file using the ``.. literalinclude::`` directive.

``literalinclude`` supports selecting parts of a file by line number, but this is obviously very finicky and breaks easily. There are two main alternatives:

If you want to include one function, class or method as a whole, you can use the ``:pyobject:`` option of ``literalinclude``:

.. code-block:: rst

    .. literalinclude:: /path/to/example.py
        :language: python
        :pyobject: my_function

If you want to include an arbitrary section of your code block, it's best to use labels / line lookup: Surround the code block you want to include with two labels / unique lines. It is possible to use the same label twice. We generally follow this style, which is best shown by an example:

.. code-block:: python

    ignore_this_variable = None

    # [include me in the docs]
    a = 3
    b = 2 * a
    assert b == 6
    # [include me in the docs]

    also_ignore_this_variable = "a"

Then, in the docs, use the ``:start-after:`` and ``:end-before:`` options of ``literalinclude`` to select only this part:

.. code-block:: rst

    .. literalinclude:: /path/to/example.py
        :language: python
        :start-after: [include me in the docs]
        :end-before: [include me in the docs]

This will result in the following code block:

.. code-block:: python

    a = 3
    b = 2 * a
    assert b == 6

There is one tiny gotcha: Our code formatter in the pipeline (black) will sometimes mess with your exact comment placement. For example, you can't have a comment directly after a top-level function or an import. This will add one or two blank lines to the end of your code block. You can leave it that way for now.

Example
-------

The following is an example for an ``.rst`` file. For more examples you can
look at other ``.rst`` files in the library.

.. code-block:: rst

    Headline 1
    ==========


    Headline 1.1
    ------------


    This is some *text*.

    .. doctest::

        >>> import math
        >>> math.sqrt(4)
        2.0