Skip to main content

rendering.APIPageRenderer

An API page that documents one or more prepared Python objects

Usage

Source

rendering.APIPageRenderer(
    node,
    level=1,
    toc_depth=_DEFAULT_SITE_TOC_DEPTH,
    *,
    renderers=_default_renderers(),
    extension=_default_extension(),
    context_page_path=None,
)

The page title in the front matter comes from the first object. A page with one object omits that object’s heading, which would repeat the title; a page with several keeps each object’s heading, one level deeper. The page’s summary rows come from its authored summary or from its objects’ own rows.

Parameter Attributes

node: (
    APIReference
    | content.DocClass
    | content.DocFunction
    | content.DocAttribute
    | content.DocTypeAlias
    | content.DocModule
    | content.Page
    | content.Section
)

The node being documented

level: int = 1

The heading depth of this appearance

toc_depth: int = _DEFAULT_SITE_TOC_DEPTH

Merged site toc-depth used to select a page override

renderers: Renderers = _default_renderers()

Renderer choices shared with nested objects, pages and summaries

extension: Extension = _default_extension()

The extension that supplies settings and project directories

A standalone renderer uses default settings and has no project directories.

context_page_path: str | None = None
The containing page’s path relative to the output directory, apart from summary links

Methods

Name Description
__post_init__() Set the page’s summary-link path and the output-relative path its objects report
object_renderers() The renderers of the page’s objects, which share the page’s context
render_body() Render the page’s objects in their authored order
render_metadata() Render the page front matter from the first object’s title and the page summary
render_summary() Render the page’s authored summary row, or else its objects’ own summary rows

__post_init__()

Set the page’s summary-link path and the output-relative path its objects report

Usage

Source

__post_init__()

object_renderers()

The renderers of the page’s objects, which share the page’s context

Usage

Source

object_renderers()

render_body()

Render the page’s objects in their authored order

Usage

Source

render_body()

Returns

BlockContent
The objects’ documentation.

render_metadata()

Render the page front matter from the first object’s title and the page summary

Usage

Source

render_metadata()

The description comes from the authored summary, or else the first object’s subject. The page raises toc-depth only when the site setting would hide members.

Returns

BlockContent
The front matter.

render_summary()

Render the page’s authored summary row, or else its objects’ own summary rows

Usage

Source

render_summary()

Summaries do not render object bodies.

Returns

Sequence[DefinitionItem]
One linked row from the authored summary, or the rows of the page’s objects.

Raises

ValueError
If the page has several objects and neither a summary nor flatten set.