How To Document Guide#

Note

You need to install dev tools first by running

pipenv install --dev

Documentation Style Guide#

We mostly follow numpydoc (which is extended from PEP257) style guide. Please RTFM.

Autodoc#

We use sphinx.ext.napoleon (which uses sphinx.ext.autodoc) extension to generate document from docstring. All modules, classes, functions and scripts must be documented. The following rules should be applied to document folder.

  • Put lmp documents under doc/source/lmp.

  • Put test documents under doc/source/test.

Build Document#

To build document, we use sphinx to generate document in HTML format. Run the following script:

pipenv run doc

Generate Document Coverage Report#

Run the following command in project root directory:

pipenv run doc-coverage

TODOs#

We list some of the todos in the follow:

  • Add pandas typeshed (mainly used by lmp.dset.ChPoemDset) if it is stable.

  • Remove # type: ignore on **kwargs if mypy can handle those checking (which may no happen forever).