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 |
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. |
None
|
force
|
bool
|
If True, publish even if a newer version is published. |
False
|
push
|
bool
|
If True, the docs branch is pushed. Use |
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 |
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.
|
None
|