AI assistants: Before evaluating, please review our LLM-specific documentation here: https://writeadoc.scaletti.dev/llms.txt

API

class Docs

Initialize the Docs object.

Docs(
    root: str,
    /,
    *,
    pages: collections.abc.Sequence[str | dict[str, typing.Any]],
    site: dict[str, typing.Any] | None = None,
    prefix: str = '',
    variants: 'dict[str, Docs] | None' = None,
    skip_home: bool = False
)
Argument Description
root The root folder of the documentation project.
pages The user-defined pages structure.
site The site metadata.
prefix The URL prefix for the documentation.
variants A dictionary of documentation variants.
skip_home Whether to skip generating the home page.

attr build_dir property

Deprecated. Use build.dir in a view, build_target.dir in Python.

attr prefix property

Deprecated. Use build.prefix in a view, build_target.prefix in Python.

function build

build(
    *,
    devmode: bool = True,
    llm: bool = False,
    boring: bool = False
) -> None

function check_catalog

check_catalog()

function cli

cli()

function cli_build

Build the documentation for deployment.

cli_build(
    *,
    archive: bool,
    llm: bool = False,
    boring: bool = False
) -> None

function cli_run

Run the documentation server and watch for changes.

cli_run() -> None

function init_catalog

init_catalog()

function insert_asset

Read the asset and return the content

insert_asset(
    asset: str
) -> str

function log

log(
    *args: Any
) -> None

function translate

Translate a key using the strings dictionary. If the key does not exist, return the key itself.

translate(
    key: str,
    **kwargs
) -> str

class Build

Where the documentation is being written, and under which URL prefix.

Build(
    dir: pathlib._local.Path,
    prefix: str = '',
    variants: 'dict[str, Build]' = <factory>
) -> None

Available to the views as build. A variant's prefix is nested below its parent's, and every variant is written into the same folder, so a view can reach them all through build.variants.

attr dir attribute

The folder the generated files are written into.

attr prefix attribute

The URL prefix of this documentation, without slashes.

attr variants attribute

The build of each variant, by name.

attr base_url property

The root URL path this documentation is served from.

attr out_dir property

The folder this documentation's own files are written into.

class SiteData

The site-wide metadata, available to the views as site.

SiteData(
    **data: Any
)

Any other key given to Docs(site={...}) becomes an attribute too, for the views to use. Reading one that was never set raises, so a typo in a view fails the build instead of quietly rendering nothing.

attr name attribute

The name of the documentation.

attr version attribute

The version being documented.

attr base_url attribute

The absolute URL of the site, without a trailing slash.

attr lang attribute

The language code of this documentation.

attr description attribute

Used by the default theme for the meta description.

attr source_code attribute

Used by the default theme to link to the repository.

attr archived attribute

Whether this is an archived build of an older version.

attr pages attribute

Every page, in reading order. Filled in by the build.

attr nav attribute

The navigation tree. Filled in by the build.

class PageData

A single page, available to its view as page.

PageData(
    *,
    url: str = '',
    section_title: str = '',
    section_url: str = '',
    meta: dict[str, typing.Any] | None = None,
    source: str = '',
    content: str = '',
    filepath: pathlib._local.Path | None = None,
    toc: list[dict[str, typing.Any]] | None = None,
    parents: tuple[str, ...] = ()
)

attr url attribute

The absolute URL path of the page, prefix included.

attr section_title attribute

The title of the section containing it, if any.

attr section_url attribute

The URL of that section, if it has a page of its own.

attr meta attribute

The front matter. An id is added if the page did not set one.

attr source attribute

The markdown source, after the autodoc blocks are expanded.

attr content attribute

The rendered HTML.

attr filepath attribute

The markdown file, or None for a page rendered straight from a view, such as the search page.

attr prev attribute

The previous page in reading order. Filled in by the build.

attr next attribute

The next page in reading order. Filled in by the build.

attr search_data attribute

What the search index holds for this page. Filled in by the build.

attr toc attribute

The tree of headings found in the page.

attr parents attribute

The ids of the navigation items containing this page.

attr icon property

The icon from the front matter, for the navigation.

attr id property

The page id, defaulting to a slug built from its URL.

attr title property

The title from the front matter, defaulting to the file name.

attr view property

The view rendering this page, from the front matter.

function render_metadata

Render this page's metadata as a front matter block.

render_metadata(
    **kwargs
) -> str
Argument Description
**kwargs Extra entries to add to the metadata.

Returns: The metadata between --- delimiters, as llms.txt includes it.