SphinxModel#
- pydantic model documenteer.conf._toml.SphinxModel#
Model for Sphinx configurations in documenteer.toml.
- Parameters:
data (
Any)
Show JSON schema
{ "title": "SphinxModel", "description": "Model for Sphinx configurations in documenteer.toml.", "type": "object", "properties": { "rst_epilog_file": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to a reStructuredText file that is added to every source file. Use this file to define common links and substitutions.", "title": "Rst Epilog File" }, "extensions": { "description": "Additional Sphinx extension.", "items": { "type": "string" }, "title": "Extensions", "type": "array" }, "nitpicky": { "default": false, "description": "Escalate warnings to build errors.", "title": "Nitpicky", "type": "boolean" }, "nitpick_ignore": { "description": "Errors to ignore. First item is the type (like a role or directive) and the second is the target (like the argument to the role).", "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array" }, "title": "Nitpick Ignore", "type": "array" }, "nitpick_ignore_regex": { "description": "Same as ``nitpick_ignore``, but both type and target are interpreted as regular expressions.", "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array" }, "title": "Nitpick Ignore Regex", "type": "array" }, "disable_primary_sidebars": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Pages that should not have a primary sidebar. Can be the page's path (without extension) or a glob of pages. By default the homepage and change logs do not have a primary sidebar.", "title": "Disable Primary Sidebars" }, "python_api_dir": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Directory path where the Python API reference documentation is created.", "title": "Python Api Dir" }, "exclude": { "description": "List of paths to exclude from being considered as Sphinx content sources.", "items": { "type": "string" }, "title": "Exclude", "type": "array" }, "theme": { "$ref": "#/$defs/ThemeModel" }, "intersphinx": { "$ref": "#/$defs/IntersphinxModel" }, "linkcheck": { "$ref": "#/$defs/LinkCheckModel" }, "redirects": { "additionalProperties": { "type": "string" }, "description": "Mapping of paths to redirect to other paths. These redirects are implemented with sphinx-rediraffe.", "title": "Redirects", "type": "object" } }, "$defs": { "IntersphinxCacheModel": { "description": "Model for the Ook intersphinx inventory cache configuration in\ndocumenteer.toml.", "properties": { "use_service": { "default": true, "description": "Prefetch intersphinx object inventories from Ook's inventory cache service so builds do not depend on third-party site availability.", "title": "Use Service", "type": "boolean" }, "service_url": { "default": "https://roundtable.lsst.cloud/ook", "description": "Base URL of the Ook API that hosts the intersphinx inventory cache service.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Service Url", "type": "string" }, "disk_cache_ttl": { "default": 600, "description": "Seconds an on-disk cached inventory stays fresh before the client revalidates it with Ook. Within this window, successive builds reuse the local file without contacting Ook at all. Set to 0 to disable the fast path so every build revalidates with Ook.", "minimum": 0, "title": "Disk Cache Ttl", "type": "integer" }, "warn_on_permanent_redirect": { "default": false, "description": "Report an intersphinx inventory URL that has permanently moved as a Sphinx warning rather than an informational message, so a warnings-as-errors (-W) build fails until the URL is updated. The warning carries the subtype documenteer.intersphinx_permanent_redirect, so it can be silenced per-project with suppress_warnings. Default is false because the move originates upstream, outside the author's control.", "title": "Warn On Permanent Redirect", "type": "boolean" } }, "title": "IntersphinxCacheModel", "type": "object" }, "IntersphinxModel": { "description": "Model for Intersphinx configurations in documenteer.toml.", "properties": { "projects": { "additionalProperties": { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, "description": "Mapping of projects and their URLs.", "title": "Projects", "type": "object" }, "cache": { "$ref": "#/$defs/IntersphinxCacheModel" } }, "title": "IntersphinxModel", "type": "object" }, "LinkCheckModel": { "description": "Model for linkcheck builder configurations in documenteer.toml.", "properties": { "ignore": { "description": "Regular expressions of URLs to skip checking links", "items": { "type": "string" }, "title": "Ignore", "type": "array" }, "use_service": { "default": true, "description": "Check links with Ook's link-check service instead of Sphinx's built-in linkcheck builder.", "title": "Use Service", "type": "boolean" }, "service_url": { "default": "https://roundtable.lsst.cloud/ook", "description": "Base URL of the Ook API that hosts the link-check service.", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Service Url", "type": "string" }, "poll_budget": { "default": 300, "description": "Maximum time (seconds) to wait for link-check results from the service.", "title": "Poll Budget", "type": "integer" }, "strict": { "default": false, "description": "Fail the build when the link-check service is unavailable instead of degrading to a warning.", "title": "Strict", "type": "boolean" }, "recheck_unverified": { "default": true, "description": "Recheck URLs the link-check service could not verify from its own vantage point \u2014 blocked by bot protection, or broken with no HTTP status code because it got no response at all \u2014 from this build's own vantage point, merging what the build observes into the report.", "title": "Recheck Unverified", "type": "boolean" }, "origin_base_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Origin base URL override for the link-check service: the full base URL of the website the links are submitted for (e.g. https://documenteer.lsst.io). By default the origin is project.base_url. The URL is normalized by lowercasing the host and stripping any trailing slash.", "title": "Origin Base Url" } }, "title": "LinkCheckModel", "type": "object" }, "ThemeModel": { "description": "Model for theme configurations in documenteer.toml.", "properties": { "show_github_edit_link": { "default": true, "description": "Show a link to edit on GitHub if True", "title": "Show Github Edit Link", "type": "boolean" }, "header_links_before_dropdown": { "default": 5, "description": "Number of links in the header nav before showing a 'More' dropdown.", "title": "Header Links Before Dropdown", "type": "integer" }, "show_last_updated": { "default": true, "description": "Show a 'Last updated' timestamp at the bottom of each page derived from Git commit dates if True", "title": "Show Last Updated", "type": "boolean" } }, "title": "ThemeModel", "type": "object" } } }
- Fields:
- field disable_primary_sidebars: list[str] | None = None#
Pages that should not have a primary sidebar. Can be the page’s path (without extension) or a glob of pages. By default the homepage and change logs do not have a primary sidebar.
- field exclude: list[str] [Optional]#
List of paths to exclude from being considered as Sphinx content sources.
- field intersphinx: IntersphinxModel [Optional]#
- field linkcheck: LinkCheckModel [Optional]#
- field nitpick_ignore: list[tuple[str, str]] [Optional]#
Errors to ignore. First item is the type (like a role or directive) and the second is the target (like the argument to the role).
- field nitpick_ignore_regex: list[tuple[str, str]] [Optional]#
Same as
nitpick_ignore, but both type and target are interpreted as regular expressions.
- field python_api_dir: str | None = None#
Directory path where the Python API reference documentation is created.
- field redirects: dict[str, str] [Optional]#
Mapping of paths to redirect to other paths. These redirects are implemented with sphinx-rediraffe.
- field rst_epilog_file: FilePath | None = None#
Path to a reStructuredText file that is added to every source file. Use this file to define common links and substitutions.
- field theme: ThemeModel [Optional]#