Contributing Documentation¶

The ccu documentation is written in reStructuredText, built with sphinx, and hosted on ReadTheDocs. To build the documentation locally, ensure that the docs extra is installed:

pip install .[docs]

Building the Documentation¶

To build the documentation, run:

sphinx-build -b html docs/source docs/build

If you have hatch installed, you can simply run:

hatch run docs:docs

Viewing the Documentation¶

To simply view the built webpage, you can launch a local web server with:

python -m http.server -d docs/build 8000

You should now be able to view the documentation by entering http://localhost:8000 into your browser.

To automatically reload the documentation upon changes to docs/source or src/ccu, run:

sphinx-autobuild -b html --watch src/ccu docs/source docs/build

or, if you have hatch installed, you can simply run:

hatch run docs:serve

Documentating API Changes¶

ccu‘s API is documented automatically from docstrings. If you add packages or modules, be sure to run sphinx-apidoc as part of the MR. Specifically, you can run the following from the projet root:

sphinx-apidoc --private -d 3 --separate --remove-old --force --module-first -H 'Package Index' --templatedir docs/source/user_guide/reference/_templates -fo docs/source/user_guide/reference/api src/ccu '**/settings*'

or, if you have hatch installed:

hatch run docs:apidoc

Tips¶

Here are some tips for writing good documentation:

Write with the purpose in mind. To what extent will the documentation serve to educate? To what extent will the documentation serve to facilitate doing? In the spirit of diataxis, is the documentation a tutorial, how-to, explanation, or reference?
Use cross-references! They make it easier for users to navigate between different pages.
Please use the no-types version of Google-style docstrings to document items:

def my_function(arg: Foo) -> Bar:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.
    Use proper sentences -- start sentences with capital letters and end
    with periods.

    Follow with Google-style sections:

    Args:
        arg: A :class:`Foo` representing foos.

    Returns:
        A :class:`Bar`.

    .. versionadded:: 6.0
    """

Type-hint all public functions/classes/modules!
Write tutorials and how-tos as doctests, where possible. Doctests are run as part of CI, so doctests offer a built-in way to check that tutorials/how-tos still work. You can verify that doctests work as expected using the doctest sphinx builder. Run:
```
sphinx-build -b doctest docs/source docs/build
```

or:

hatch run docs:linkcheck

Verify that links work as expected using the linkcheck sphinx builder. Run:
```
sphinx-build -b linkcheck docs/source docs/build
```

or:

hatch run docs:linkcheck