Adding documentation#

Documentation should be fairly simple as long as the class/function docstrings are correctly written.

Style guidelines#

scikit-digital-health uses NumPy Docstrings

Adding documentation#

The one place to be careful when documenting classes is to make sure that the class docstring occurs directly below the class definition. Other than this, the docstrings will be automatically scanned and generated, with the appropriate call in __init__.py.

Documentation of the your new module occurs almost fully in the __init__.py file for the module. This will contain any information on the module, how it works, as well as any relevant background information (e.g. Gait). For another good reference from NumPy, see the numpy.fft page.

Next is the file directing Sphinx to automatically find and document the custom module, docs/ref/custom_module.rst. Finally, to make the new module show up in the API reference, add it to the docs/ref/index.rst toctree!

src/skdh/custom_module/__init__.py

"""
IMU <Custom Module> (:mod:`skdh.custom_module`)
===============================================

.. currentmodule:: skdh.custom_module

Inertial sensor <custom module>
-------------------------------

.. _Remove the `` below

.. ``autosummary``::
    :toctree: generated/

    CustomClass  .. _this is the name of your class

Headline 2
----------
content
"""
from skdh.custom_module.custom_module import CustomModule

docs/ref/custom_module.rst

..
    _Give it a custom explicit reference label

.. _skdh custom-module:

.. automodule:: skdh.custom_module
    :ignore-module-all:

docs/ref/index.rst

.. _skdh api reference:

API Reference
=============

.. toctree::
    :maxdepth: 2

    gait
    sit2stand
    read
    custom_module

And thats it! Before pushing and creating a pull request, make sure that the documentation builds properly:

Make sure all the requirements are installed (pyproject.toml docs dependencies)
Run the following in the terminal:

# make sure you are in the docs folder
cd docs
# generate the html documentation
make html
# inspect the generated docs
open _build/html/index.html