Skip to main content

extensions.Extension

The API reference extension that setup(extension) receives

Usage

Source

extensions.Extension(
    settings,
    source=None,
    *,
    output_root=None,
)

Great Docs creates a new Extension each time it generates the API reference, so cache starts empty and every object is prepared afresh. Hooks registered globally through great_docs.hooks are shared by every run and keep their own state.

During setup, register hooks, select renderers with set_renderers and declare inputs with watch. Registration closes when setup returns. Setup may read settings, source_root, config_root and output_root but must not change them.

Object and docstring hooks change the documentation that every alias of an object shares, including whether the object is excluded. Keep their edits to the object’s own docstring and metadata. Use a renderer to customise how an object appears on a page.

Attributes

settings

The parser, introspection and rendering settings. Read-only.

source_root

The project’s documentation source directory, or None outside a project.

config_root

The directory of the selected configuration file, or None outside a project.

output_root

The directory the documentation is generated into, or None when nothing is written.

cache: dict[str, object]
The extension’s own values, shared by setup and its callbacks for one run.

Methods

Name Description
on_object_resolved() Register an object hook, which runs on each object before its docstring is parsed
on_docstring_parsed() Register a docstring hook, which runs on each object’s parsed docstring sections
set_renderers() Select the renderer classes; call this during setup
watch() Declare a file, directory or glob that the extension reads

on_object_resolved()

Register an object hook, which runs on each object before its docstring is parsed

Usage

Source

on_object_resolved(
    self,
    callback: ObjectResolvedHook,
    priority: int = 0,
) -> ObjectResolvedHook
on_object_resolved(
    self,
    callback: None = None,
    priority: int = 0,
) -> Callable[[ObjectResolvedHook], ObjectResolvedHook]

A hook may edit the object’s docstring or documentation metadata, or exclude the object. It must leave the object’s members, bases and descendants as they are. Every alias of the object shares the result, including an exclusion. To change how the object looks in one place, use a renderer method or a body callback.

Parameters

callback: ObjectResolvedHook | None = None

A callable that receives the Griffe object, never an alias. Return that object, a replacement, or None to exclude it. Omit callback to use this method as a decorator.

priority: int = 0
The run order. Lower values run first, and equal values run in registration order, with global hooks before the ones registered here.

Returns

ObjectResolvedHook | Callable[[ObjectResolvedHook], ObjectResolvedHook]
callback, or a decorator that registers one when callback is omitted.

Raises

RuntimeError
If setup has finished or the extension is closed.

on_docstring_parsed()

Register a docstring hook, which runs on each object’s parsed docstring sections

Usage

Source

on_docstring_parsed(
    self,
    callback: DocstringParsedHook,
    priority: int = 0,
) -> DocstringParsedHook
on_docstring_parsed(
    self,
    callback: None = None,
    priority: int = 0,
) -> Callable[[DocstringParsedHook], DocstringParsedHook]

Docstring hooks run only for objects that have a docstring. Every alias, reference page, the text export and symbol queries use the sections they return. A hook may change the object’s own sections but must leave its members and descendants as they are.

Parameters

callback: DocstringParsedHook | None = None

A callable that receives the prepared object and its list of parsed sections, and returns the sections to keep, which may include replacements. It must not return None. Omit callback to use this method as a decorator.

priority: int = 0
The run order. Lower values run first, and equal values run in registration order, with global hooks before the ones registered here.

Returns

DocstringParsedHook | Callable[[DocstringParsedHook], DocstringParsedHook]
callback, or a decorator that registers one when callback is omitted.

Raises

RuntimeError
If setup has finished or the extension is closed.

set_renderers()

Select the renderer classes; call this during setup

Usage

Source

set_renderers(renderers)

Parameters

renderers: Renderers
The renderer choices. Kinds left out keep the default renderer.

Raises

RuntimeError

If setup has finished or the extension is closed.

TypeError
If renderers is not a Renderers instance.

watch()

Declare a file, directory or glob that the extension reads

Usage

Source

watch(path)

A relative path resolves against the extension file’s directory. Declared inputs count towards the reference fingerprint and preview watches them, but Great Docs does not copy them into the generated project.

Parameters

path: str | Path
A file, directory or glob, which need not exist yet. The final fingerprint covers a directory’s entries and the files a glob matches. A running preview keeps watching the paths it started with, so restart it after declaring an input outside them.

Raises

RuntimeError

If setup has finished or the extension is closed.

ValueError
If there is no extension file.