CitationModel

pydantic model documenteer.conf._toml.CitationModel

Model for an entry in the [[project.citations]] array of documenteer.toml.

An entry carries both the work’s bibliographic fields and the presentation fields that say how the site displays it. The bibliographic fields can instead come from a CITATION.cff file, named by cff, in which case a field set here overrides the file’s value; the presentation fields are only ever set here.

Parameters:

data (Any)

Show JSON schema

{
   "title": "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.",
   "type": "object",
   "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"
      }
   },
   "$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"
      }
   }
}

Config:

• populate_by_name: bool = True

• validate_by_alias: bool = True

• validate_by_name: bool = True

Fields:

• authors (list[documenteer.conf._toml.CitationAuthorModel])

• cff (str | None)

• date (datetime.date | None)

• doi (str | None)

• in_footer (bool | None)

• is_self (bool)

• label (str | None)

• note (str | None)

• publisher (str | None)

• title (str | None)

Validators:

• validate_doi » doi

field authors: list[CitationAuthorModel] [Optional]

The work’s authors, in the order they should be credited. Setting any author replaces the whole author list a cff file supplies.

field cff: str | None = None

Path to a CITATION.cff file supplying the bibliographic fields, relative to documenteer.toml (typically ../CITATION.cff).

field date: datetime.date | None = None

The work’s publication date. Only its year appears in a rendered citation.

field doi: str | None = None

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.

Validated by:

• validate_doi

field in_footer: bool | None = None

Whether this citation appears in the site footer. Defaults to true for the self entry and false for every other.

field is_self: bool = False (alias 'self')

Whether this is the DOI whose landing page this site is. At most one entry can set it.

field label: str | None = None

A short label distinguishing this citation from the site’s others, such as “Dataset” or “Paper”.

field note: str | None = None

Free text about when to use this citation, displayed alongside it.

field publisher: str | None = None

The organization that published the work.

field title: str | None = None

The title of the cited work.

validator validate_doi  »  doi

Normalize the DOI to its bare form, rejecting a non-DOI.

Parameters:

v (str | None)

Return type:

str | None

property shows_in_footer: bool

Whether the citation appears in the site footer, resolving the default from whether it is the self citation.