ConfigRoot#
- pydantic model documenteer.conf._toml.ConfigRoot#
The root model for a documenteer.toml configuration file.
- Parameters:
data (
Any)
Show JSON schema
{ "title": "ConfigRoot", "description": "The root model for a documenteer.toml configuration file.", "type": "object", "properties": { "project": { "$ref": "#/$defs/ProjectModel" }, "sphinx": { "anyOf": [ { "$ref": "#/$defs/SphinxModel" }, { "type": "null" } ], "default": null } }, "$defs": { "CitationAuthorModel": { "description": "Model for an author of a ``[[project.citations]]`` entry.\n\nAn author is either a person, named with ``family_name`` (and usually\n``given_name``), or an organization, named with ``name``. The split\nmatters to a rendered citation: a person's name is set family-name-first\nand may be abbreviated by a BibTeX style, where an organization's is\nprotected from both.", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The organization's name, for an author that is an institution rather than a person.", "title": "Name" }, "ror": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The organization's ROR (ror.org) identifier. Only meaningful alongside ``name``.", "title": "Ror" }, "family_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person's family name (last name in western culture).", "title": "Family Name" }, "given_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person's given name (first name in western culture).", "title": "Given Name" }, "orcid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person's ORCID, as a URL or a bare identifier. Only meaningful alongside ``family_name``.", "title": "Orcid" }, "affiliation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The person's affiliation, as a single display name. Only meaningful alongside ``family_name``.", "title": "Affiliation" } }, "title": "CitationAuthorModel", "type": "object" }, "CitationModel": { "description": "Model for an entry in the ``[[project.citations]]`` array of\ndocumenteer.toml.\n\nAn entry carries both the work's bibliographic fields and the\npresentation fields that say how the site displays it. The bibliographic\nfields can instead come from a CITATION.cff file, named by ``cff``, in\nwhich case a field set here overrides the file's value; the presentation\nfields are only ever set here.", "properties": { "doi": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The work's DOI, written bare (``10.NNNN/suffix``), as a https://doi.org/ URL, or with a ``doi:`` prefix. Required unless a ``cff`` file supplies one.", "title": "Doi" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "A short label distinguishing this citation from the site's others, such as \"Dataset\" or \"Paper\".", "title": "Label" }, "self": { "default": false, "description": "Whether this is the DOI whose landing page this site is. At most one entry can set it.", "title": "Self", "type": "boolean" }, "in_footer": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether this citation appears in the site footer. Defaults to true for the ``self`` entry and false for every other.", "title": "In Footer" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Free text about when to use this citation, displayed alongside it.", "title": "Note" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The title of the cited work.", "title": "Title" }, "authors": { "description": "The work's authors, in the order they should be credited. Setting any author replaces the whole author list a ``cff`` file supplies.", "items": { "$ref": "#/$defs/CitationAuthorModel" }, "title": "Authors", "type": "array" }, "publisher": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The organization that published the work.", "title": "Publisher" }, "date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ], "default": null, "description": "The work's publication date. Only its year appears in a rendered citation.", "title": "Date" }, "cff": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to a CITATION.cff file supplying the bibliographic fields, relative to documenteer.toml (typically ``../CITATION.cff``).", "title": "Cff" } }, "title": "CitationModel", "type": "object" }, "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" }, "OpenApiDocsModel": { "description": "Model for OpenAPI documentation configurations in documenteer.toml.", "properties": { "generator": { "anyOf": [ { "$ref": "#/$defs/OpenApiGeneratorModel" }, { "type": "null" } ], "default": null, "description": "The function that generates the OpenAPI spec file from theapplication source code. If not specified, the OpenAPI spec file assumed to be generated by an external process and provided at the path specified by ``openapi_path``." }, "openapi_path": { "default": "_static/openapi.json", "description": "This is the path, relative to the Sphinx conf.py file, where the OpenAPI spec file is written. Default is ``_static/openapi.json``.", "title": "Openapi Path", "type": "string" }, "doc_path": { "default": "api", "title": "Doc Path", "type": "string" } }, "title": "OpenApiDocsModel", "type": "object" }, "OpenApiGeneratorModel": { "description": "Specification for the OpenAPI generator function used by the\n``documenteer.ext.openapi`` Sphinx extension.", "properties": { "function": { "description": "The Python function that generates the OpenAPI spec file. It must have the form ``module:func``. The function must return a JSON-serialized string.", "title": "Function", "type": "string" }, "positional_args": { "description": "Positional arguments to pass to the generator function.", "items": {}, "title": "Positional Args", "type": "array" }, "keyword_args": { "additionalProperties": true, "description": "Keyword arguments to pass to the generator function.", "title": "Keyword Args", "type": "object" } }, "required": [ "function" ], "title": "OpenApiGeneratorModel", "type": "object" }, "ProjectModel": { "description": "Model for the project table in the documenteer.toml file.", "properties": { "title": { "description": "Name of the project, used as titles throughout the documentation site.", "title": "Title", "type": "string" }, "base_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Canonical URL of the site's root page.", "title": "Base Url" }, "copyright": { "default": "", "description": "Copyright statement, without a 'copyright' prefix word.", "title": "Copyright", "type": "string" }, "github_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "The URL of the project's GitHub repository.", "title": "Github Url" }, "github_default_branch": { "default": "main", "description": "The project's default development branch on GitHub.", "title": "Github Default Branch", "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Version string.", "title": "Version" }, "python": { "anyOf": [ { "$ref": "#/$defs/PythonPackageModel" }, { "type": "null" } ], "default": null }, "openapi": { "anyOf": [ { "$ref": "#/$defs/OpenApiDocsModel" }, { "type": "null" } ], "default": null }, "citations": { "description": "Citations the site displays, in the order they appear in the footer.", "items": { "$ref": "#/$defs/CitationModel" }, "title": "Citations", "type": "array" } }, "required": [ "title" ], "title": "ProjectModel", "type": "object" }, "PythonPackageModel": { "description": "Model for a Python package (i.e. built with pyproject.toml-compatible\nbuild system.", "properties": { "package": { "description": "Package name", "title": "Package", "type": "string" }, "documentation_url_key": { "default": "Homepage", "description": "Key for the documentation URL in the pyproject.toml [project.urls] table. The corresponding URL is used for the Sphinx html_baseurl configuration, which in turns sets the canonical URL link relation on the web pages.", "title": "Documentation Url Key", "type": "string" }, "github_url_key": { "default": "Source", "description": "Key for the documentation URL in the pyproject.toml [project.urls] table. The corresponding URL is used for as an alternative to setting [project.github_url].", "title": "Github Url Key", "type": "string" } }, "required": [ "package" ], "title": "PythonPackageModel", "type": "object" }, "SphinxModel": { "description": "Model for Sphinx configurations in documenteer.toml.", "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" } }, "title": "SphinxModel", "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" } }, "required": [ "project" ] }
- Fields:
- field project: ProjectModel [Required]#
- field sphinx: SphinxModel | None = None#