# extensions.Extension

The API reference extension that `setup(extension)` receives

Usage

[Source](https://github.com/posit-dev/great-docs/blob/main/great_docs/_apiref/_customisation.py#L42-L675)

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

Great Docs creates a new [Extension](../reference/extensions.Extension.md#great_docs.extensions.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](../reference/extensions.Extension.md#great_docs.extensions.Extension.set_renderers) and declare inputs with [watch](../reference/extensions.Extension.md#great_docs.extensions.Extension.watch). Registration closes when setup returns. Setup may read `settings`, [source_root](../reference/rendering.RenderContext.md#great_docs._apiref._rendering._context.RenderContext.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()](#great_docs.extensions.Extension.on_object_resolved) | Register an object hook, which runs on each object before its docstring is parsed |
| [on_docstring_parsed()](#great_docs.extensions.Extension.on_docstring_parsed) | Register a docstring hook, which runs on each object's parsed docstring sections |
| [set_renderers()](#great_docs.extensions.Extension.set_renderers) | Select the renderer classes; call this during setup |
| [watch()](#great_docs.extensions.Extension.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](https://github.com/posit-dev/great-docs/blob/main/great_docs/_apiref/_customisation.py#L239-L271)

``` python
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](https://github.com/posit-dev/great-docs/blob/main/great_docs/_apiref/_customisation.py#L283-L315)

``` python
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](https://github.com/posit-dev/great-docs/blob/main/great_docs/_apiref/_customisation.py#L317-L336)

``` python
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](../reference/rendering.BaseRenderer.md#great_docs._apiref._rendering.base.BaseRenderer.renderers) is not a [Renderers](../reference/rendering.Renderers.md#great_docs.rendering.Renderers) instance.

### watch()

Declare a file, directory or glob that the extension reads

Usage

[Source](https://github.com/posit-dev/great-docs/blob/main/great_docs/_apiref/_customisation.py#L338-L364)

``` python
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.
