Contributing guide#
Code style#
Docs#
We use sphinx-gallery to generate the tutorials. The source file should be placed in kliff/examples and the file name should start with
example_
.To generate the docs (including the tutorials), do:
$ cd kliff/docs $ make html
The generated docs will be at
kliff/docs/build/html/index.html
.The above commands will not only parse the docstring in the tutorials, but also run the codes in the tutorials. Running the codes may take a long time. So, if you just want to generate the docs, do:
$ cd kliff/docs $ make html-notutorial
This will not run the code in the tutorials.
Below is Mingjian’s personal notes on how to generate API docs. Typically, you will not need it.
To generate the API docs for a specific module, do:
sphinx-apidoc -f -o <TARGET> <SOURCE>
where <TARGET> should be a directory where you want to place the generated .rst file, and <SOURCE> is path to your Python modules (should also be a directory). For example, to generate docs for all the modules in kliff, you can run (from the kliff/docs directory)
sphinx-apidoc -f -o tmp ../kliff
After generating the docs for a module, make necessary modifications and then move the .rst files in tmp to kliff/docs/apidoc.
Note
The kliff/docs/apidoc/kliff.rst is referenced in index.rst, serving as the entry for all docs.