How to Contribute
=================================
Current documentation site is built with a python documentation generator, Sphinx_, and hosted in Github.
In order to make modifications, the changes need to be built with Sphinx, and the generated html files must be
committed to the Github repository.


How to add a new document
--------------------------
The Sphinx reads rst (ReStructuredText) files. For a quick reference, please checkout `here <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_.

Clone our repo ``https://github.com/ECP-CANDLE/Candle.git`` and create a new file inside ``docs_/source/`` directory.
You can start a directory structure under the source directory, if you want to organize files. Just make sure your changes are reflected in the index file.

Don't forget to **link** the new document in the index file. If you want to link from the top level, please add in ``docs_/source/index.rst``.


How to add CANDLE Library API
------------------------------
1. create rst file in `docs_/source/candle_lib/`
2. add to `docs_/source/candle_lib.rst` for index


How to build html
------------------
The html files are generated by Github action automatically. Just commit the changes add new docs and push to master branch.


How to convert asciidoc format to rst
--------------------------------------
Sphinx by default does not support Asciidoc and do not have plan to support in near future (check this issue_ for detail).
However, Pandoc_, a univeral document convert, can be used to convert rst format. For example,

.. code-block:: shell

    # install pandoc first. Refer the pandoc website for installation.

    # target format rst (-t), output file (-o)
    $ pandoc -t rst -o new_rst_file.rst input_asciidoc_file.adoc

    # convert markdown to rst
    $ pandoc -t rst -o new_rst_file.rst input_markdown_file.md
  ..


.. _issue: https://github.com/rtfd/readthedocs.org/issues/17
.. _Pandoc: https://pandoc.org/
.. _Sphinx: http://www.sphinx-doc.org/en/master/