Skip to content

Doc

📖 This page describes the invoke_tasklib.doc module, which provides tasks to publish versioned documentation with mike, on top of MkDocs.

Overview

Task Behavior
doc.build Builds the docs, failing on warnings
doc.serve Serves the docs locally
doc.publish-dev Publishes development (unstable) docs
doc.publish-latest Publishes latest (stable) docs

All four tasks read paths.docs_config from the resolved config (default: docs/mkdocs.yml). The two publish tasks pass it to mike via --config-file, and doc.build and doc.serve pass it to mkdocs. If the file does not exist, the tasks exit with 2 and name tasklib.paths.docs_config, before running anything.

Publishing Development Docs

invoke doc.publish-dev

Deploys the current docs under the main version with the dev alias (mike deploy replaces an existing main version, so it is not deleted first), then pushes to the configured remote (typically gh-pages). Pass --no-push to only commit the docs branch locally.

Publishing Latest (Stable) Docs

invoke doc.publish-latest

Determines the version to publish from the highest git release tag (a tag like v1.2.3, read with git tag --list 'v[0-9]*'; pre-release tags such as v1.2.0rc1 are ignored, but a suffix like v1.2.0-backport is not a pre-release), truncated to <major>.<minor> (e.g. 1.2). It then deploys the current docs under that tag with the latest alias, and sets latest as the default version shown to visitors. Pass --no-push to only commit the docs branch locally.

To publish a specific version without looking at the git tags, pass it explicitly:

invoke doc.publish-latest --version 1.2

The task fails if there is no version tag and no --version, because publishing under a made-up version would be a setup error. Pre-release versions (1.2.0rc1, 1.2.0a1, 1.2.0.dev1, ...) are skipped, so they never become latest.

The task also refuses to move latest backwards: if a newer <major>.<minor> is already published (mike list --json), for example when releasing a 1.1.5 backport after 1.2.0, it fails with Refusing to publish 1.1 as latest. Pass --force to publish the older version anyway.

Local Preview

The publishing tasks are meant for CI (they --push to the remote). To check and preview docs locally:

invoke doc.build
invoke doc.serve

doc.build runs mkdocs build --strict, so a broken link or a missing reference fails the task (unlike a mike deploy into a throw-away branch, which does not). doc.serve runs mkdocs serve with live reload. Both use paths.docs_config and need the docs dependency group.

doc.build and doc.serve take --args for mkdocs, for example invoke doc.serve --args "--dev-addr 127.0.0.1:8001".

See Also