digitalfabrik/integreat-cms

**********************
Documentation (Sphinx)
**********************

To generate this documentation, we use the Python documentation generator Sphinx (see :doc:`sphinx:usage/index`).

The generation process is divided into two stages:

1. :doc:`sphinx:man/sphinx-apidoc` is a tool which scans the whole source code of our application in the ``integreat_cms``
   directory and generates ``.rst`` files out of the Python docstrings. These files are then placed in the
   ``docs/src/ref-ext`` directory.
2. :doc:`sphinx:man/sphinx-build` generates the html documentation out of the ``.rst`` files located in the sphinx directory.
   It merges the static ``.rst`` files directly in the ``sphinx`` directory together with the files generated in step 1
   in ``docs/src/ref-ext`` and the simplified ``.rst`` files in ``docs/src/ref``.

Developer Tools
===============

Generate this documentation with :github-source:`tools/make_docs.sh`::

    ./tools/make_docs.sh [--clean]

Apart from the two steps above, this tool also performs the additional tasks:

* :github-source:`Patch <docs/src/patches/footer.diff>` the footer template
  which allows custom URLs in the copyright notice.

* Move the translation file to make sure the documentation doesn't get partially translated.

* Modify the autogenerated ``.rst`` files to improve the readability by removing module paths in headings.

* :github-source:`Patch <docs/src/patches/cms.diff>` the autogenerated ``~integreat_cms.cms.rst`` file to make sure decorated functions
  are included in the documentation.

* Copy all ``.rst`` files in ``docs/src/ref-ext`` to the directory ``docs/src/ref`` and remove all undocumented and
  inherited members from the simplified version.

* :github-source:`Patch <docs/src/patches/breadcrumbs.diff>` the breadcrumbs template which allows links from the simple
  view to the extended view and vice versa

* Remove all temporary build files when running in CircleCI context to exclude them from the contents hosted on GitHub Pages.

If the ``--clean`` parameter is provided, the script will clean all temporary documentation files in the ``docs/src/ref/``
and ``docs/src/ref-ext/`` directories as well as the compiled html output in ``docs/dist``. Existing outdated documentation
files can cause the generation script to fail if e.g. source files were added or deleted.

.. include:: _docstrings.rst

Cross-referencing
=================

Whenever you want to reference another module, class or function inside a static documentation page or within a
docstring, use the according :doc:`sphinx:usage/restructuredtext/domains` and have a look at :ref:`sphinx:python-xref-roles`.

Example:
``:class:`~integreat_cms.cms.models.regions.region.Region``` becomes :class:`~integreat_cms.cms.models.regions.region.Region`

Many other python projects also use Sphinx for their documentation. Whenever you use e.g. a library function or want
to reference external classes or documentation pages, you can do this with :mod:`~sphinx:sphinx.ext.intersphinx`.
All available documentations are listed in the dict :const:`~conf.intersphinx_mapping`.
If you want to reference another documentation which is not yet listed, just add it to this dict. After that, you can
reference them with the normal directives plus the key specified in the :const:`~conf.intersphinx_mapping` dict.

Example:
``:doc:`python:howto/regex`` becomes :doc:`python:howto/regex`

.. Note::

    If the cross-referenced documentation uses `custom text roles <https://docutils.sourceforge.io/docs/howto/rst-roles.html>`__,
    the usage of these custom roles will only work after these roles have been registered in an extension's ``setup()``
    (see :class:`sphinx.application.Sphinx`).


.. Hint::

    If you don't know which references to the external documentation are possible, you can use the tool `sphobjinv <https://pypi.org/project/sphobjinv/>`__::

        sphobjinv suggest -u https://docs.python.org/3.9/objects.inv "regex"

        Remote inventory found.

        :std:doc:`howto/regex`
        :std:label:`regex-howto`

Substitutions
=============

Whenever you use GitHub-specific strings, please use :ref:`default-substitutions`:

* ``|github-username|`` becomes |github-username|

* ``|github-repository|`` becomes |github-repository|

* ``|github-pages-url|`` becomes |github-pages-url|

If you want to provide new substitutions, add them to :const:`~conf.rst_epilog`.

GitHub Pages
============

The CircleCI job ``deploy-documentation`` uses the GitHub user `DigitalfabrikMember <https://github.com/DigitalfabrikMember>`__ to
push all changes to the documentation on the ``develop`` branch to our repository's ``gh-pages`` branch.
This branch is then automatically deployed to |github-pages-url|.

External Links
==============

Whenever you use multiple external links to the same website, consider defining a shortcut in :const:`~conf.extlinks`.
Currently, the following shortcuts exists:

* ``:github:``, e.g. ``:github:`issues``` is rendered to :github:`issues`
* ``:github-issue:``, e.g. ``:github-issue:`1928``` is rendered to :github-issue:`1928`
* ``:github-source:``, e.g. ``:github-source:`setup.py``` is rendered to :github-source:`setup.py`
* ``:django-source:``, e.g. ``:django-source:`django/shortcuts.py``` is rendered to :django-source:`django/shortcuts.py`

.. _sphinx-extensions:

Extensions
==========

We use the following sphinx extensions:

* :mod:`sphinx:sphinx.ext.autodoc` allows to use directives like ``automodule`` in ``.rst`` files to automatically
  import the modules and pull in documentation from docstrings in a semi-automatic way.

* :mod:`sphinx:sphinx.ext.extlinks` allows to use shortcuts to external links defined in :const:`~conf.extlinks`.

* :mod:`sphinx:sphinx.ext.githubpages` creates a ``.nojekyll`` file on generated HTML directory to publish the document
  on GitHub Pages.

* :mod:`sphinx:sphinx.ext.intersphinx` allows to reference other project's documentations.

* :mod:`sphinx:sphinx.ext.linkcode` adds external links to the source code of documented modules, see
  :func:`~conf.linkcode_resolve`.

* :mod:`sphinxcontrib_django` adds improvements to the docstrings of Django models and forms.

* `sphinx_rtd_theme <https://pypi.org/project/sphinx-rtd-theme/>`__ is the theme we use for our documentation:
  :doc:`sphinx-rtd-theme:index`

* `sphinx_last_updated_by_git <https://pypi.org/project/sphinx-last-updated-by-git/>`__ determines the "last updated"
  date on the generated html documentation by the modification date of the source files in git.


Configuration
=============

.. automodule:: conf
    :members: