Writing documentation
*********************
This section describes certain not obvious details in writing documentation for PyDistSim in sphinx.

Build locally
=============

To build the documentation locally, create a new virtual environment and install the requirements from ``docs/requirements.txt``.
Then run ``make html`` in the ``docs`` directory.

The documentation will be built in ``docs/_build/html``.


Intersphinx
===========

To auto-reference external document in with intersphinx in docs, use ```:py:<type>:`<ref>``` i.e. ``:py:class:`numpy.poly1d```.

The intersphinx mapping is defined in ``source/conf.py``. The mapping is defined as a dictionary with the key being the name of the
mapping and the value being the URL of the mapping. Automatic population of the mapping is done with the extension ``seed_intersphinx_mapping``.


readthedocs.org
===============

To add the documentation to readthedocs.org, create an account and add the repository. The documentation will be built automatically
since the configuration file ``.readthedocs.yml`` is present in the repository.