Contributing guide#

Code style#

  • KLIFF uses black to format the code. It adopts the default style of black. To format the code, one can use:

    black <filename>.py
    

    Supply --skip-string-normalization to black to avoid changing single quote to double quote (not recommended).

  • The docstring of KLIFF follows the Google style, which can be found at googledoc.

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.