.. _creating_docs:

Creating Pyddg Docs Locally
===========================

- The **Pyddg Documentation** consists of:

  - the **Users Guide** (created from the ``.rst`` files located in pyddg/docs)
  - the **Developers Guide** (also created from ``.rst`` files)
  - the **API docs** (created from all docstrings of functions and classes)

- The version of the **documentation** on **develop** can be found 
  `online <https://www.discretization.de/pyddg/doc/>`_ and is updated
  automatically when pushing onto develop:

Creating Documentation Locally
------------------------------

You can also create the html documentation **locally**.

If you haven't set up your development environment already, see
:ref:`developers_installation`. Now in your directory ``pyddg`` run

.. code-block:: bash

    poetry shell

which will spawn a new poetry shell.

To create the **whole documentation**, execute from pyddg directory:

.. code-block:: bash

    make -C docs/ docs
    firefox docs/build/index.html

API Documentation Coverage
~~~~~~~~~~~~~~~~~~~~~~~~~~

Check what parts of the library are covered by the API docs.

.. code-block:: bash

    make -C docs/ coverage

and find the list of undocumented parts in ``pyddg/docsbuild/coverage/python.txt``.