Sphinx

# Build environment API

class sphinx.environment.BuildEnvironment

  Attributes

  app

    Reference to the `Sphinx` (application) object.

  config

    Reference to the `Config` object.

  project

    Target project. See `Project`.

  srcdir

    Source directory.

  doctreedir

    Directory for storing pickled doctrees.

  events

    An `EventManager` object.

  found_docs

    A set of all existing docnames.

  metadata

    Dictionary mapping docnames to “metadata” (see File-wide metadata).

  titles

    Dictionary mapping docnames to the docutils node for their main title.

  docname

    Returns the docname of the document currently being parsed.

  parser

    Returns the parser being used for to parse the current document.

  Per-document attributes

  current_document

    Temporary data storage while reading a document.

    Extensions may use the mapping interface provided by `env.current_document` to store data relating to the current document, but should use a unique prefix to avoid name clashes.

    Important

    Only the following attributes constitute the public API. The type itself and any methods or other attributes remain private, experimental, and will be changed or removed without notice.

    current_document.docname: str

      The document name (‘docname’) for the current document.

    current_document.default_role: str

      The default role for the current document. Set by the default-role directive.

    current_document.default_domain: Domain | None

      The default domain for the current document. Set by the `default-domain` directive.

    current_document.highlight_language: str

      The default language for syntax highlighting. Set by the `highlight` directive to override the `highlight_language` config value.

    current_document._parser: Parser | None

      This attribute is experimental and may be changed without notice.

      The parser being used to parse the current document.

  Utility methods

  doc2path(docname: str, base: bool = True) → _StrPath

    Return the filename for the document name.

    If base is True, return absolute path under self.srcdir. If base is False, return relative path to self.srcdir.

  relfn2path(filename: str | Path, docname: str | None = None) → tuple[str, str]

    Return paths to a file referenced from a document, relative to documentation root and absolute.

    In the input “filename”, absolute filenames are taken as relative to the source dir, while relative filenames are relative to the dir of the containing document.

  note_dependency(filename: str | PathLike[str], *, docname: str | None = None) → None

    Add filename as a dependency of the current document.

    This means that the document will be rebuilt if this file changes.

    filename should be absolute or relative to the source directory.

  new_serialno(category: str = '') → int

    Return a serial number, e.g. for index entry targets.

    The number is guaranteed to be unique in the current document.

  note_reread() → None

    Add the current document to the list of documents that will automatically be re-read at the next build.