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.

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¶

create rst file in docs_/source/candle_lib/
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,

  # 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
..