Documentation development

The documentation is built from the makrdown files in the /docs directory with static site generator MkDocs.

With make

Makefile

The following commands are encoded in a Makefie in this repository: makefile.

Serve

To serve the documentation locally, you can the serve_docs target:

make serve_docs

The documentation is served on http://localhost:8000/.

Build

To build the documentation, you can the build_docs target:

make build_docs

The documentation is built in the /site directory.

Deploy

To deploy the documentation to GitHub Pages, you can the deploy_docs target:

make deploy_docs

The documentation is deployed to GitHub Pages.

By hand

In order to serve the documentation by hand follow the steps below.

Note

The commands need to be run from the root of the repository, unless stated otherwise.

1. Install the documentation-related dependancies and the Python package itself with Poetry

poetry install

1. Document the API of the package

lucidoc cloudwatcher --parse rst --outfile docs/API_documentation.md

1. Run the following command in the project root

mkdocs serve

Deploying the documentation

In order to deploy the documentation run the following command:

mkdocs gh-deploy