Skip to content

Doc

invoke_tasklib.doc

Documentation build and publishing tasks (doc.*).

doc.build and doc.serve run mkdocs on the config file of tasklib.paths.docs_config; doc.publish-dev and doc.publish- latest deploy the versioned documentation with mike. A project without documentation can use all the other tasks: only these tasks read paths.docs_config, and they exit with the code 2 when the file does not exist.

invoke_tasklib.doc.NAMESPACE module-attribute

NAMESPACE = 'doc'

The name of the namespace of the tasks of this module.

invoke_tasklib.doc.build

build(c: Context, *, args: str | None = None) -> None

Build the documentation and fail on any warning.

The documentation is built with mkdocs build --strict from paths.docs_config, so a broken link or a missing reference fails the task. It does not publish anything.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to mkdocs.

None

Raises:

Type Description
UnexpectedExit

If mkdocs reports a warning or an error.

invoke_tasklib.doc.publish_dev

publish_dev(c: Context, *, push: bool = True) -> None

Publish development (e.g. unstable) docs.

The main version is deployed with the dev alias. An existing main version is replaced by mike deploy, so it is not deleted first (a failed deployment would otherwise remove it).

Parameters:

Name Type Description Default
c Context

The invoke context.

required
push bool

If True, the docs branch is pushed. Use --no-push to commit it locally only.

True

invoke_tasklib.doc.publish_latest

publish_latest(
    c: Context,
    *,
    version: str | None = None,
    force: bool = False,
    push: bool = True,
) -> None

Publish latest (e.g. stable) docs.

The docs are published as <major>.<minor> of the version with the latest alias, and latest is set as the default version. Pre-release versions (1.2.0rc1) are skipped. The task refuses to publish a version that is older than one that is already published (for example a 1.1.5 backport after 1.2.0), because it would move latest backwards, unless force is set.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
version str | None

The version to publish, e.g. "1.2" or "1.2.3". Defaults to the last git version tag (v1.2.3).

None
force bool

If True, publish even if a newer version is published.

False
push bool

If True, the docs branch is pushed. Use --no-push to commit it locally only.

True

Raises:

Type Description
Exit

If no version is given and no version tag exists, or if the version cannot be parsed, or if a newer version is already published and force is False.

invoke_tasklib.doc.serve

serve(c: Context, *, args: str | None = None) -> None

Serve the documentation locally with live reload.

The server runs until it is interrupted (Ctrl+C).

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to mkdocs, e.g. "--dev-addr 127.0.0.1:8001".

None