Users Guide Conventions & Writing Entries

Conventions and policies for our online docs

(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 Creating Pyddg Docs Locally.

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 local table of contents 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.

RST Converter

If you need to convert one markup format to another, you can use pandoc, 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 might be useful to you.

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:

.. 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:

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

Consult the sphinx docs for more detail.

Emdedding GIFs

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

Maths

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

The new edge length are calculated as follows

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

Or in inline mode:

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.

Doctests

Everything in 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:

.. 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:

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:

.. 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:

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.

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


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


This is some *text*.

.. doctest::

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