livery.extensions.mkdocstrings._pages¶
livery.extensions.mkdocstrings._pages ¶
The python API reference: a page per module, and the nav block that lists them.
The mkdocstrings step of the docs phase runs once per package whose
set holds python and writes the package's reference into its generated
tree: a page per module of each of its roots under api/, each a
single ::: directive that the python handler renders with the
module's members, and the api nav block that lists the pages,
nav.api.toml, which the site places in the package's section. Both
are rebuilt whole, so a module that went takes its page with it, and a
package that declines its reference with [docs] api = false keeps
neither.
The handler reads a package's modules from its sources and from the
directories the step's paths option names, and its options and
inventories are the ones the site's config writes
(the docs.config answer in this extension's _config module).
The pages and the block are data the docs extension reads: the
generated tree is docs/_generated/ in the package, and the block is
the file nav.api.toml in it, a nav list of one-key tables, each
a label to a page path inside the package's docs/. This extension
writes both itself.
Functions:
| Name | Description |
|---|---|
documented |
Whether the reference documents package, by the extensions its set holds. |
declines_api |
Whether package turns its reference off with |
roots |
The importable roots under src: each topmost directory with an |
pages |
(page path, dotted import path) per module of each root, public first. |
declared_paths |
The directories package's |
sources |
The handler's search paths for package, relative to the workspace root. |
write_reference |
Write package's API pages and its nav block; the pages written. |
pages_run |
Write the API reference of the package the run names: the docs phase's step. |
Attributes:
| Name | Type | Description |
|---|---|---|
STEP |
|
|
GENERATED_DIR |
|
|
API_DIR |
|
|
NAV_BLOCK |
|
|
INVENTORIES |
|
|
OPTIONS |
dict[str, object]
|
|
OPTIONS
module-attribute
¶
OPTIONS: dict[str, object] = {'docstring_style': 'google', 'show_if_no_docstring': True, 'show_root_heading': True, 'show_root_full_path': True, 'separate_signature': True, 'show_signature_annotations': True, 'signature_crossrefs': True, 'members_order': 'source', 'merge_init_into_class': True, 'summary': True, 'heading_level': 2}
documented ¶
Whether the reference documents package, by the extensions its set holds.
A package whose set holds an extension the step names, python, is documented; any other is never asked. The step is read from the installed declaration in a process that mounted nothing, as the site's config may be.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
declines_api ¶
Whether package turns its reference off with [docs] api = false.
The key is the docs extension's, read here from the package's contract as data.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
roots ¶
The importable roots under src: each topmost directory with an __init__.py.
Shallowest first, then by path. A directory with no __init__.py
is a namespace and marks nothing, so a package under one is a root
of its own, and a package under a root is part of that root.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
pages ¶
(page path, dotted import path) per module of each root, public first.
Every module gets a page, underscore-private included: a docstring
is published the moment it is written. Public sorts before private
at every level of the tree, and a package's __init__ is its
index page. A package that ships more than one root, as a wheel
shipping two does, documents each: the shallowest root's pages sit
at the reference's top, and each further root's under a directory
named by its dotted path, after them. A package may decline the
whole reference with [docs] api = false, the shape a forwarding
shim takes: its surface is another package's, and documenting the
forwarders would document the real thing twice.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
declared_paths ¶
The directories package's paths option names, relative to the package.
Directories holding modules the pages reference beyond the package's sources: rendered stubs, for one. A value that is not a list of strings refuses naming the contract.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
sources ¶
The handler's search paths for package, relative to the workspace root.
Its sources while it has pages, then the directories its paths
option names.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
write_reference ¶
Write package's API pages and its nav block; the pages written.
One page per module, each a single directive, under api/ in
the generated tree the site's mount merges, so the pages publish
under the package's own path, and the block listing them beside
them. Both are rebuilt whole: a package with no page now keeps
neither.
Source code in packages/extensions/mkdocstrings/src/livery/extensions/mkdocstrings/_pages.py
pages_run ¶
pages_run(ctx: PhaseContext) -> None
Write the API reference of the package the run names: the docs phase's step.
The pages and the nav block of write_reference, the count said.