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:
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.
Created: 2023-06-07 22:19:32+0000