.. _creating_docs:

Building the documentation
==========================

You can create the html documentation locally.
The documentation is generated using `sphinx <https://www.sphinx-doc.org/>`_
from the files located under `docs/source` onto the folder `docs/build`.

We rely on some external packages to automate the generation of the documentation:

  - To generate automatic documentation for API, we use `sphinxcontrib-apidoc <https://github.com/sphinx-contrib/apidoc>`_.
  - To automatically generate the documentation for different versions of pyddg, we use `sphinx-multiversion <https://github.com/Holzhaus/sphinx-multiversion>`_.
  - To generate a coverage report, we use the `coverage extension <https://www.sphinx-doc.org/en/master/usage/extensions/coverage.html>`_.

Setup
-----

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.

Building the documentation quickly
----------------------------------

To create the whole documentation for the **current state of the repository**,
execute from pyddg directory:

.. code-block:: bash

	make -C docs/ html

This command is usefull for quick iteration as **results are cashed**,
so only modified files are computed again.

Note though that this command bypasses version information and differs in that way
from the command run in the CI pipeline to build the documentation.

You can specify `build options <https://www.sphinx-doc.org/en/master/man/sphinx-build.html#options>`_
to the underlying sphinx command.

.. code-block:: bash

   export SPHINXOPTS='-j auto'
   make -C docs html

You can clean the build directory manually using this command:

.. code-block:: bash

	make -C docs/ clean

To clean before building run:

.. code-block:: bash

	make -C docs/ docs

which is equivalent to running

.. code-block:: bash

	make -C docs/ clean
	make -C docs/ html
	
To visualize the html pages you can run:

.. code-block:: bash
				
	firefox docs/build/index.html
	
Building the current version of the documentation
-------------------------------------------------

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

.. code-block:: bash

	python3 test.py -d

This is the default used in the CI pipeline, so succeeding in running this command
should ensure that the pipeline will pass for the build of the documentation.

Since the build is based on the current branch,
it will not take any non-commited changes into account
and a detached head will result in an error.

Also, running this command will automatically clean the build directory
before running and no caching will be performed.

You can build the docs using multiple cores with:

.. code-block:: bash

	python3 test.py -d -- -j auto

To visualize the documentation for the current branch in a browser you can run:

.. code-block:: bash

   firefox docs/build/pyddg/doc/<current-branch-name>/index.html

For example to visualize the documentation for the develop branch run:

.. code-block:: bash

   firefox docs/build/pyddg/doc/develop/index.html

Building all the versions of the documentation
----------------------------------------------

To build **all the versions** of the documentation, execute from pyddg directory:

.. code-block:: bash

	python3 test.py -D

This behavior must be triggered manually in the CI pipeline to run.

This command will as well clean the build folder before running.

It is recommended to run this command on multiple cores if you have some:

.. code-block:: bash

	python3 test.py -D -- -j auto

Since the multiple versions of the documentation are interacting with each other via javascript,
you need to spawn a webserver to visualize them properly

.. code-block:: bash

	python3 -m http.server --directory docs/build &
	firefox localhost:8000
	
API Documentation Coverage
--------------------------

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

.. code-block:: bash

	make -C docs/ coverage

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