.. _development-sphinx:

Sphinx
======

In the following section we explain how to contribute to this documentation.

If you are reading the HTML version on http://openPMD-api.readthedocs.io and want to improve or correct existing pages, check the "Edit on GitHub" link on the right upper corner of each document.

Alternatively, go to ``docs/source`` in our source code and follow the directory structure of `reStructuredText`_ (``.rst``) files there.
For intrusive changes, like structural changes to chapters, please open an issue to discuss them beforehand.

.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html

Build Locally
-------------

This document is build based on free open-source software, namely `Sphinx`_, `Doxygen`_ (C++ APIs as XML) and `Breathe`_ (to include doxygen XML in Sphinx).
A web-version is hosted on `ReadTheDocs`_.

.. _Sphinx: https://github.com/sphinx-doc/sphinx
.. _Doxygen: http://doxygen.org
.. _Breathe: https://github.com/michaeljones/breathe
.. _ReadTheDocs: https://readthedocs.org/

The following requirements need to be installed (once) to build our documentation successfully:

.. code-block:: bash

    cd docs/

    # doxygen is not shipped via pip, install it externally,
    # from the homepage, your package manager, conda, etc.
    # example:
    sudo apt-get install doxygen graphviz

    # python tools & style theme
    python -m pip install -r requirements.txt # --user


With all documentation-related software successfully installed, just run the following commands to build your docs locally.
Please check your documentation build is successful and renders as you expected before opening a pull request!

.. code-block:: bash

    # skip this if you are still in docs/
    cd docs/

    # render the `.rst` files and replace their macros within
    #   enjoy the breathe errors on things it does not understand from doxygen :)
    make html

    # open it, e.g. with firefox :)
    firefox build/html/index.html

    # now again for the pdf :)
    make latexpdf

    # open it, e.g. with okular
    build/latex/openPMD-api.pdf


Useful Links
------------

 * `A primer on writing restFUL files for sphinx <http://www.sphinx-doc.org/en/stable/rest.html>`_
 * `Why You Shouldn't Use "Markdown" for Documentation <http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`_
 * `Markdown Limitations in Sphinx <https://docs.readthedocs.io/en/latest/getting_started.html#in-markdown>`_