Contributing
===================================
-----------------
How to contribute
-----------------

Here should go the developers guide.


----------------------
Creating documentation
----------------------

If you want to create a new page in the documentation that is not related to the API, you can create a new .rst file in the docs/source folder.
You can learn more about the reStructuredText format in `reStructuredText`_.

.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

----------------------------
Generating API documentation
----------------------------

To generate the documentation, we use Sphinx. Notice that any new function or class that you add to asparagus
should be documented using the numpydoc format. You can find more information about the numpydoc
format in `numpydoc`_.

.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html.

To automatically generate the documentation of the api, we used the command of sphinx-apidoc,
you can run it by using the following command:

.. code-block:: bash

    sphinx-apidoc -f -o docs/source/api asparagus


More information about the sphinx-apidoc command can be found `sphinx-apidoc`_.

.. _sphinx-apidoc: https://www.sphinx-doc.org/en/master//man/sphinx-apidoc.html

We recommend that you make a test of the documentation before pushing your changes to the repository. This can be done by running the following command:

.. code-block:: bash

   mkdir test_docs
   sphinx-build docs/source test_docs
   firefox test_docs/index.html

This will create a folder called test_docs and will open the documentation in firefox. You can replace firefox with the browser of your choice.
Once you are satisfied with the documentation you can push your changes to the repository.

**Note**: The documentation is automatically generated by the readthedocs platform.


-----------------
Questions
-----------------

Please create an issue in the repository if you have any questions.