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

Configuration¤

There are several options for documentation configuration:

DDYP_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).

DDYP_MKDOCS_CODE_PARCE_SOURCE_PATH¤

default: "dd_yandex_pay"

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

DDYP_MKDOCS_CODE_PARCE_DOCS_PATH¤

default: "reference"

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

DDYP_MKDOCS_CODE_PARCE_SHOW_NAV¤

default: false

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

DDYP_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.

DDYP_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.

DDYP_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.

But before pushing the updated documentation, please run the hatch run docs:build-check command, it will build the documentation with rigth parameters and check the links for broken ones.

Documentation is collected in GitHub Actions and uploaded to the gh-pages branch and published using GitHub Pages.

The documentation is automatically collected and rolled out when pushing the release tag (v*), and when pushing to the dev branch, the dev version of the documentation is updated.

You can learn more about these processes in the release and dev workflow configs.

Last update: 2023-09-28 15:16:22+0000
Created: 2023-09-21 22:12:30+0000
Authors: Dmitry Dobrynin