Documentation Generation

Documentation for DivBase is generated using MkDocs along with the Material for MkDocs theme.

The mkdocs.yml at the root of the repository contains the configuration for the docs site and all content inside the docs/ folder can be used to create the documentation pages.

To add a new page to the documentation site you must add it to the nav: section of the mkdocs.yml file.

View documentation locally

To build and serve the documentation locally, you can use the following command:

mkdocs serve --livereload

The docs will be available at: http://localhost:8008/divbase/

If you make changes to the documentation files inside the docs/ folder, the local server will automatically reload to reflect those changes. Changes to the mkdocs.yml file require a restart of the server to take effect.

Automated CLI documentation generation

Some of the documentation pages, are autogenerated from the codebase. This is covered by a "hook" which runs on initial build of the docs site. Hooks can be defined in the mkdocs.yml file. See scripts/build_docs.py.

Deploying the documentation site

A GH action is set up to automatically build and deploy the documentation site to GitHub pages on workflow dispatch or if a new release is created. The action uses the mkdocs gh-deploy command to build and deploy the site.