GreatDocs.build()

Build the documentation site.

Usage

Source

GreatDocs.build(
    watch=False,
    refresh=True,
    version_tags=None,
    latest_only=False,
    jobs=None,
)

Generates API reference pages followed by quarto render. By default, re-discovers package exports and updates the API reference configuration before building.

Note

In practice, you would normally use the great-docs build CLI command rather than calling this method directly. See the CLI reference for details.

Parameters

watch: bool = False

If True, watch for changes and rebuild automatically.

refresh: bool = True

If True (default), re-discover package exports and update API reference config before building. Set to False for faster rebuilds when your package API hasn’t changed.

version_tags: list[str] | None = None

If provided, only build these specific version tags (for multi-version sites). Ignored when no versions: config is present.

latest_only: bool = False

If True, build only the latest version (skip historical versions). Ignored when no versions: config is present.

jobs: int | str | None = None

Experimental. Render the pages of a single-version site with this many Quarto processes at once. Use a number, or "auto" to choose one from the CPU count. The default (None) reads the GREAT_DOCS_RENDER_JOBS environment variable and otherwise renders in one process. Sites that can’t be split safely are rendered in one process anyway. Ignored for multi-version sites and in watch mode.

Raises

FileNotFoundError

If the project has no great-docs.yml.

BuildError

If the build fails and leaves no usable site: Quarto is missing or too old, a configured reference name is missing from the installed package, the API reference cannot be generated, or Quarto fails to render the site. The failure has already been reported in the build log or on standard error.

Examples

Build the documentation (with API refresh):

from great_docs import GreatDocs

docs = GreatDocs()
docs.build()

Build with watch mode:

docs.build(watch=True)

Quick rebuild without API refresh:

docs.build(refresh=False)