Overview

The documentation for Apache Open Climate Workbench is built using Sphinx which relies on reStructuredText. Please check the appropriate sites for additional information.

We follow PEP 8 as closely as possible!

Docstrings

  • Each function should have a docstring immediately following it (see Example below).
  • We follow PEP 257 for our general docstring formatting while using Sphinx notation for annotating parameters and building documentation.
  • Please pay particular attention to the notes in PEP 257. Specifically, "The docstring ... prescribes the function or method's effect as a command ('Do this', 'Return that'), not as a description; e.g. don't write 'Returns the pathname ...'".

    • Multiline docstring. Please be sure to use intersphinx when appropriate so we get good linking between project documentation.

      def some_func(param1, param2)
    """ One line description of function

    Longer description of function goes here if necessary

    This description can be multiple paragraphs

    :param param1: The first parameter that we don't use
    :type param1: :mod:`string`
    :param param2: The second parameter that we don't use
    :type param2: :class:`list` of :class`float`

    :returns: Nothing since this function doesn't do anything
	:rtype: None. We really don't need to have this line here!
    """
    pass

How to use PyLint

If you are contributing to this code base then you will need to comply with the code convention standards set forth by the project team.
If you don't have PyLin you can easily install it with

pip install pylint

Any time you make a contribution you should run your changes through PyLint. You should be leaving the file in a better/equivalent state to which you found it.

 

Note, there is a RC file for pylint in the root directory of the project. You should use this RC file when running pylint on the project's code. An example run:

export OCW_HOME=/path/to/project/root
pylint --rcfile=$OCW_HOME/.pylintrc <optional file to check>
  • No labels