extensions.Extension
The API reference extension that setup(extension) receives
Usage
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
Noneoutside a project. config_root-
The directory of the selected configuration file, or
Noneoutside a project. output_root-
The directory the documentation is generated into, or
Nonewhen 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
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
Noneto exclude it. Omitcallbackto 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 whencallbackis 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
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. Omitcallbackto 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 whencallbackis omitted.
Raises
RuntimeError- If setup has finished or the extension is closed.
set_renderers()
Select the renderer classes; call this during setup
Usage
set_renderers(renderers)Parameters
renderers: Renderers- The renderer choices. Kinds left out keep the default renderer.
Raises
watch()
Declare a file, directory or glob that the extension reads
Usage
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.