Structure

Files

Documentation always starts in <module root>/doc/index.rst.

Small modules may have only this file with all chapters included. Documentation for larger modules should be organized into several files and subfolders, for example:

<module root>/doc/index.rst
<module root>/doc/integration.rst
<module root>/doc/configuration.rst
<module root>/doc/generator.rst
<module root>/doc/api.rst
<module root>/doc/examples.rst
<module root>/doc/limitations.rst
<module root>/doc/internal.rst

In this case, use a non-hidden toctree at the end of <module root>/doc/index.rst:

.. toctree::

    integration
    configuration
    generator
    api
    examples
    limitations
    internal

Additional resources, such as images, should also be added to the doc folder, for example:

<module root>/doc/integration/generators/abc/overview.png
<module root>/doc/integration/generators/abc/concept.png
<module root>/doc/integration/generators/abc/integration.png

Main Page

When creating a module, you are not expected to document everything in the first pull request, except for the Introduction. The Introduction should always be placed in <module root>/doc/index.rst.

If the documentation is split into several files, do not add an explicit heading:

myModule
========

<introduction text>

.. toctree::

    ...

If the documentation is all in one file without a toctree, add a heading for Introduction:

myModule
========

Introduction
------------

<introduction text>

Other Chapter
-------------

...