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" }, "CitationDefaultsModel": { "additionalProperties": false, "description": "Model for the ``[project.citation_defaults]`` table of\ndocumenteer.toml.\n\nA site that mints a DOI per data product declares dozens of\n``[[project.citations]]`` entries that agree about almost everything: the\nsame publisher, the same one-element author list, the same year, the same\ntype. This table states each of those once, and every entry that leaves\nthe field unstated takes it, so an entry is written as the handful of\nfields that tell one work from another.\n\nOnly the *bibliographic* fields are accepted, and only the ones a site's\nworks can genuinely share. Identity and presentation are per work \u2014 a\nDOI, a URL, a title, a label, a page, a note, a BibTeX key, the ``self``\nand ``preferred`` claims, and the CITATION.cff file one entry reads each\nname a single work \u2014 so a default for any of them would be a value no\nentry could use. Writing one is a configuration error rather than a\nsilently ignored key, which is also what catches a misspelling of a key\nthe table does accept.", "properties": { "type": { "anyOf": [ { "$ref": "#/$defs/CitationType" }, { "type": "null" } ], "default": null, "description": "The kind of work each entry that states no ``type`` is." }, "publisher": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The organization that published each entry that names no ``publisher``.", "title": "Publisher" }, "date": { "anyOf": [ { "$ref": "#/$defs/PartialDate" }, { "type": "null" } ], "default": null, "description": "The publication date of each entry that states no ``date``, written in any of the forms an entry's own ``date`` accepts." }, "authors": { "description": "The authors of each entry that names none. An entry that names any author replaces this list rather than adding to it.", "items": { "$ref": "#/$defs/CitationAuthorModel" }, "title": "Authors", "type": "array" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The release each entry that names no ``version`` is cited at, such as a data release's ``DP2.1``.", "title": "Version" } }, "title": "CitationDefaultsModel", "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 for the ``self`` entry; every other entry may instead be located by ``url``. A ``cff`` file can supply either.", "title": "Doi" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The work's landing page, which locates a work that has no DOI, as an absolute http or https URL. A ``cff`` file supplies one from its ``url``, or from its ``repository-code`` when it states no landing page.", "title": "Url" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "A short label for this citation, shown as the heading of its card and in the site footer, such as \"Dataset\" or \"TAP\". It is a display string and need not be unique: a citation's identity is its bibtex_key, which the build keeps distinct across the site.", "title": "Label" }, "type": { "anyOf": [ { "$ref": "#/$defs/CitationType" }, { "type": "null" } ], "default": null, "description": "The kind of work being cited, which decides the schema.org type the site publishes it under. A cff file supplies one when this is unset." }, "self": { "default": false, "description": "Whether this site is this DOI's registered landing page. At most one entry can set it. It says nothing about which citation the site asks readers to use, which is ``preferred``.", "title": "Self", "type": "boolean" }, "preferred": { "default": false, "description": "Whether this is the citation the site asks readers to use. At most one entry can set it; it defaults to the ``self`` entry when the site has one.", "title": "Preferred", "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 preferred entry and for the ``self`` entry \u2014 the same entry unless the site separates them \u2014 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" }, "page": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The page inside this site that is the DOI's registered landing page, as a Sphinx docname with an optional fragment (``products/catalogs/object#tap``). Unset means the site as a whole is the landing page.", "title": "Page" }, "bibtex_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The key this citation's BibTeX entry is written under, such as ``RTN-115``. Defaults to the site's lsst.io subdomain for the entry describing this site's own work, to the DOI for any other entry that has one, and to author-year-title otherwise. Set it to pin a key a manuscript already cites.", "title": "Bibtex Key" }, "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" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The release of the work being cited, such as a package's 12.3.0. A ``cff`` file supplies one from its ``version``. A software entry that describes this site's own package \u2014 one that sets ``self``, ``preferred``, or ``cff_preferred = false`` \u2014 defaults to the project's own version when neither states one.", "title": "Version" }, "date": { "anyOf": [ { "$ref": "#/$defs/PartialDate" }, { "type": "null" } ], "default": null, "description": "The work's publication date, stated to the precision its source knows: a TOML date (2025-06-30), a bare year (2025), or a quoted ISO 8601 date (\"2025-06\" or \"2025\"). Only its year appears in a rendered citation." }, "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" }, "cff_preferred": { "default": true, "description": "Whether a preferred-citation in the ``cff`` file is the record read, as GitHub's \u201cCite this repository\u201d button does. Set it false to cite the file's top-level record \u2014 the software or dataset the repository itself is \u2014 instead.", "title": "Cff Preferred", "type": "boolean" } }, "title": "CitationModel", "type": "object" }, "CitationType": { "description": "The kind of work a citation describes.\n\nThis is the citation's counterpart to DataCite's\n``resourceTypeGeneral``: it says what the cited thing *is*, which is what\ndecides the schema.org type a landing page publishes it under (see\n``SCHEMA_ORG_TYPES``). A work whose type is unstated is not forced into one\n\u2014 an untyped citation keeps the generic default \u2014 so the vocabulary can\nstay small and every member can mean something definite.", "enum": [ "dataset", "article", "software", "report", "other" ], "title": "CitationType", "type": "string" }, "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" }, "PartialDate": { "description": "A publication date stated to the precision its source knows.\n\nA bibliographic source rarely states a full day. A ``.bib`` file, a\njournal's front matter, and a CITATION.cff reference commonly give a year\nalone, and DataCite's own mandatory metadata is a ``publicationYear``.\nCarrying such a date as a `datetime.date` would mean inventing a month and\na day \u2014 and since Documenteer publishes the date as schema.org\n``datePublished``, the invented day would then be asserted as fact on\nevery page of a site. ISO 8601 spells reduced precision as ``YYYY`` and\n``YYYY-MM``, schema.org ``Date`` is ISO 8601, and DataCite's crosswalk\nmaps ``publicationYear`` onto ``datePublished`` as a bare year; this type\nis that spelling.\n\nA rendered citation shows only the year at every precision, so stating a\ndate to the year costs a reader nothing: only the machine-readable\nmetadata tells the three precisions apart.", "properties": { "year": { "title": "Year", "type": "integer" }, "month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Month" }, "day": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Day" } }, "required": [ "year" ], "title": "PartialDate", "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" }, "citation_defaults": { "$ref": "#/$defs/CitationDefaultsModel", "description": "Bibliographic fields the ``[[project.citations]]`` entries share, filling in each entry that states none of its own. A table declared by a site with no citations is inert." } }, "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#