Skip to content

Documentation¤

To develop documentation, use mkdocs with the theme mkdocs-material.

Sources for documentation generation parse mkdocstring-python which can handle multiple formats, we use Google-style (this only applies to docstrings), but not pure, and its variation is napoleon (But of course this is a debatable issue, and we can change if there are suggestions).

Local development¤

In the simplest case, running a local server with development documentation would look like this:

$ hatch run docs:serve

Building and publishing¤

There is a separate hatch run docs:build command for the documentation build.

Documentation is published automatically and configured in readthedocs.

Configuration¤

There are several options for documentation configuration:

MERINGUE_MKDOCS_CODE_PARCE_ENABLED¤

default: true

Enabling / disabling the output of sources in the documentation "on-the-fly" (organized based on the example from the mkdocstrings documentation).

MERINGUE_MKDOCS_CODE_PARCE_SOURCE_PATH¤

default: "meringue"

A directory with sources for "on-the-fly" generation.

MERINGUE_MKDOCS_CODE_PARCE_DOCS_PATH¤

default: "reference"

Documentation directory for displaying "on-the-fly" generated source documentation.

MERINGUE_MKDOCS_CODE_PARCE_SHOW_NAV¤

default: false

Parameter for debugging generated "on-the-fly" navigation.

MERINGUE_MKDOCS_ENABLED_GIT_REVISION_DATE¤

default: true

Option to enable/disable modification dates for documentation files. It will be useful to disable it when developing locally so that the console is not clogged with errors.

MERINGUE_MKDOCS_OFFLINE¤

default: false

Parameter for building documentation into a build working from a folder, without the need to start the server. read more about the mechanism here.

MERINGUE_MKDOCS_ENABLE_MINIFY¤

default: true

Parameter to enable plugin minify minifying html, js and css when generating documentation.

When working with local server documentation, this option is disabled.

Building and publishing¤

There is a separate hatch run docs:build command for building documentation.

The documentation build is produced in GitHub Actions and published in GitHub Pages.

Documentation is rolled out dev version when pushing to dev branch and release when pushing tags with v* versions.

Explore .github/workflows/mkdocs-dev.yml and .github/workflows/mkdocs-release.yml if necessary.


Last update: 2023-07-04 00:51:54+0000
Created: 2023-06-07 22:19:32+0000
Authors: dd