DocumenteerConfig#

class documenteer.conf.DocumenteerConfig(conf, root_dir=<factory>)#

Bases: object

Configuration from a documenteer.toml file.

Parameters:

conf (ConfigRoot)
root_dir (Path, default: <factory>)

Attributes Summary

`automodapi_toctreedirm`
`base_url`	Base root URL for the site.
`citations`	The citations declared in `[[project.citations]]`, resolved and composed, in the order they are declared.
`conf`
`copyright`	The copyright statement.
`github_url`	The project's GitHub repository.
`header_links_before_dropdown`	Number of links to show in the nav head before folding extra items into a More dropdown.
`intersphinx_cache_disk_cache_ttl`	Seconds an on-disk cached inventory stays fresh before the client revalidates it with Ook (0 disables the fast path).
`intersphinx_cache_service_url`	Base URL of the Ook API that hosts the intersphinx inventory cache service (without a trailing slash).
`intersphinx_cache_use_service`	Whether to prefetch intersphinx inventories from Ook's inventory cache service.
`intersphinx_cache_warn_on_permanent_redirect`	Whether a permanently-moved intersphinx inventory URL is reported as a Sphinx warning (failing a `-W` build) rather than at info level.
`linkcheck_origin_base_url`	The origin base URL for the link-check service.
`linkcheck_poll_budget`	Maximum time (seconds) to wait for link-check results from the service.
`linkcheck_recheck_unverified`	Whether URLs the link-check service could not verify from its own vantage point — bot-blocked, or broken with no response at all — are rechecked from the build's own vantage point, with the local observations merged into the report.
`linkcheck_service_url`	Base URL of the Ook API that hosts the link-check service (without a trailing slash).
`linkcheck_strict`	Whether link-check service degradation fails the build.
`linkcheck_use_service`	Whether to check links with Ook's link-check service instead of Sphinx's built-in linkcheck builder.
`nitpicky`
`project`	Project title.
`redirects`	Redirects defined in the [sphinx.redirects] TOML configuration.
`root_dir`	The directory the documenteer.toml file was loaded from.
`rst_epilog`	Content of the user's reStructuredText epilog, or an empty string if not set.
`rst_epilog_path`	Path to the user's reStructuredText epilog file, if set.
`self_citation`	The citation whose DOI landing page this site is, or `None` if no entry claims it.
`show_last_updated`	Whether to show a "Last updated" timestamp at the bottom of each page derived from Git commit dates.
`version`	The project's version.

Methods Summary

`append_extensions`(extensions)	Append user-configured extensions to an existing list.
`append_linkcheck_ignore`(link_patterns)	Append URL patterns for sphinx.linkcheck.ignore to existing patterns.
`append_nitpick_ignore`(nitpick_ignore)
`append_nitpick_ignore_regex`(nitpick_ignore_regex)
`disable_primary_sidebars`(html_sidebars)
`extend_exclude_patterns`(exclude_patterns)	Extend Sphinx `exclude_patterns` with the "exclude" configuration from the sphinx TOML table.
`extend_intersphinx_mapping`(mapping)	Extend the `intersphinx_mapping` dictionary with configured projects.
`find_and_load`()
`load`(toml_content, *[, root_dir])
`set_citations`(html_context)	Publish the resolved citations into Sphinx's `html_context`.
`set_edit_on_github`(html_theme_options, ...)	Configure the Edit on GitHub functionality, if possible.

Attributes Documentation

automodapi_toctreedirm#

base_url#

Base root URL for the site.

The URL is obtained in this order:

The base_url field of the [project] table in documenteer.toml.
From importlib.metadata if [project.python] is set in documenteer.toml.
Default is “”.

citations#

The citations declared in [[project.citations]], resolved and composed, in the order they are declared.

Returns:: A GuideCitation per entry, each pairing the bibliographic record with the presentation fields that say how the site displays it. Empty when the site declares no citations.
Return type:: list
Raises:: sphinx.errors.ConfigError – Raised if an entry names a CITATION.cff file that cannot be read, or if neither the entry nor its CITATION.cff file yields the DOI and title a citation needs.

Notes

Resolution reads any referenced CITATION.cff file, so it is deferred to first access and then cached: a configuration that is loaded but never displays a citation does no I/O.

conf: ConfigRoot = <dataclasses._MISSING_TYPE object>#

copyright#

The copyright statement.

Default is "" if not set.

github_url#

The project’s GitHub repository.

The GitHub URL is obtained in this order:

The project.github_url field in documenteer.toml
From importlib if the project.python table is set
Default is None.

header_links_before_dropdown#: Number of links to show in the nav head before folding extra items into a More dropdown.

intersphinx_cache_disk_cache_ttl#: Seconds an on-disk cached inventory stays fresh before the client revalidates it with Ook (0 disables the fast path).

intersphinx_cache_service_url#: Base URL of the Ook API that hosts the intersphinx inventory cache service (without a trailing slash).

intersphinx_cache_use_service#: Whether to prefetch intersphinx inventories from Ook’s inventory cache service.

intersphinx_cache_warn_on_permanent_redirect#: Whether a permanently-moved intersphinx inventory URL is reported as a Sphinx warning (failing a -W build) rather than at info level.

linkcheck_origin_base_url#

The origin base URL for the link-check service.

The origin is the [sphinx.linkcheck] origin_base_url override if set; otherwise it is the project’s base URL. Either way it is normalized (lowercased host, trailing slash stripped) to match the service’s origin normalization. None if neither is available.

linkcheck_poll_budget#: Maximum time (seconds) to wait for link-check results from the service.

linkcheck_recheck_unverified#: Whether URLs the link-check service could not verify from its own vantage point — bot-blocked, or broken with no response at all — are rechecked from the build’s own vantage point, with the local observations merged into the report.

linkcheck_service_url#: Base URL of the Ook API that hosts the link-check service (without a trailing slash).

linkcheck_strict#: Whether link-check service degradation fails the build.

linkcheck_use_service#: Whether to check links with Ook’s link-check service instead of Sphinx’s built-in linkcheck builder.

nitpicky#

project#: Project title.

redirects#: Redirects defined in the [sphinx.redirects] TOML configuration.

root_dir: Path = <dataclasses._MISSING_TYPE object>#

The directory the documenteer.toml file was loaded from.

Paths in the configuration that are documented as relative to documenteer.toml — a citation’s cff file, for instance — are resolved against this directory. Sphinx runs conf.py with the configuration directory as the working directory, so the default (the working directory) is right for a build.

rst_epilog#: Content of the user’s reStructuredText epilog, or an empty string if not set.

rst_epilog_path#: Path to the user’s reStructuredText epilog file, if set.

self_citation#: The citation whose DOI landing page this site is, or None if no entry claims it.

show_last_updated#: Whether to show a “Last updated” timestamp at the bottom of each page derived from Git commit dates.

version#

The project’s version.

The version is obtained in this order:

project.version field in documenteer.toml
From importlib if the project.python table is set
Default is “Latest”.

Methods Documentation

append_extensions(extensions)#

Append user-configured extensions to an existing list.

Parameters:: extensions (list[str])
Return type:: None

append_linkcheck_ignore(link_patterns)#

Append URL patterns for sphinx.linkcheck.ignore to existing patterns.

Parameters:: link_patterns (list[str])
Return type:: None

append_nitpick_ignore(nitpick_ignore)#

Parameters:: nitpick_ignore (list[tuple[str, str]])
Return type:: None

append_nitpick_ignore_regex(nitpick_ignore_regex)#

Parameters:: nitpick_ignore_regex (list[tuple[str, str]])
Return type:: None

disable_primary_sidebars(html_sidebars)#

Parameters:: html_sidebars (MutableMapping[str, list[str]])
Return type:: None

extend_exclude_patterns(exclude_patterns)#

Extend Sphinx exclude_patterns with the “exclude” configuration from the sphinx TOML table.

Parameters:: exclude_patterns (list[str])
Return type:: None

extend_intersphinx_mapping(mapping)#

Extend the intersphinx_mapping dictionary with configured projects.

Parameters:: mapping (MutableMapping[str, tuple[str, str | None]])
Return type:: None

classmethod find_and_load()#

Return type:: DocumenteerConfig

classmethod load(toml_content, *, root_dir=None)#

Parameters:

toml_content (str)
root_dir (Path | None, default: None)

Return type:

DocumenteerConfig

set_citations(html_context)#

Publish the resolved citations into Sphinx’s html_context.

Parameters:: html_context (MutableMapping[str, Any]) – The Sphinx html_context mapping to populate.
Return type:: None

Notes

Two keys are set, and only when the site declares at least one citation, so that a site without [[project.citations]] renders exactly as it did before:

documenteer_citations: Every citation, in declaration order, as the mapping to_html_context composes.
documenteer_self_citation: The entry from that list whose is_self is true, or None.

This is the whole contract with the surfaces that display a citation — the <head> metadata, the citation-card directive, and the footer — which read the context and never recompose a citation.

set_edit_on_github(html_theme_options, html_context)#

Configure the Edit on GitHub functionality, if possible.

The in-repository path of the documentation source is not set here; it is resolved from the Sphinx source directory by the documenteer.ext.githubeditlink extension, which is the earliest point where the source directory is known.

Parameters:

html_theme_options (MutableMapping[str, Any])
html_context (MutableMapping[str, Any])

Return type:

None