.. _developer_documentation_build:

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

**Before submitting a pull request check if your modifications have introduced
new sphinx warnings by building the documentation locally and try to fix them.**

.. prompt:: bash

    pip install '.[doc]'

To build the documentation, you need to be in the `docs` folder:

.. prompt:: bash

    cd docs

In the vast majority of cases, you only need to generate the web site without
the example gallery (equivalent to ``make html-noplot``):

.. prompt:: bash

   make

The documentation will be generated in the ``_build/html/`` directory
and are viewable in a web browser, for instance by opening the local
``_build/html/index.html`` file.
To also generate the example gallery you can use:

.. prompt:: bash

    make html

This will run all the examples, which takes a while. You can also run only 
a few examples based on their file names.
Here is a way to run all examples with filenames containing "dcrt":

.. prompt:: bash

    EXAMPLES_PATTERN="dcrt" make html

You can use regular expressions for more advanced use cases.

In the case of a PR, you can look at the version generated by circle ci, by
looking at the details of `Check the rendered docs here!`.

Debugging the documentation
---------------------------

1. Docstring of functions:
    For any errors or warnings in the doctring, the best way to fix it 
    is to copy the doctring in a file and use the command `rst2html`.
    This command is provided by sphinx.
2. Example error with sphinx gallery:
    If there is an error which appears when the documentation is generated and not 
    when the example is run alone, In this case, you should use the file 
    `documentation/debbugger_script/run_debug_example.py`