Back to Sphinx

Build environment API

doc/extdev/envapi.rst

9.1.02.5 KB
Original Source

Build environment API

.. module:: sphinx.environment

.. class:: BuildEnvironment

Attributes

.. attribute:: app

  Reference to the :class:`.Sphinx` (application) object.

.. attribute:: config

  Reference to the :class:`.Config` object.

.. attribute:: project

  Target project.  See :class:`.Project`.

.. attribute:: srcdir

  Source directory.

.. attribute:: doctreedir

  Directory for storing pickled doctrees.

.. attribute:: events

  An :class:`.EventManager` object.

.. attribute:: found_docs

  A set of all existing docnames.

.. attribute:: metadata

  Dictionary mapping docnames to "metadata" (see :ref:`metadata`).

.. attribute:: titles

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

.. autoattribute:: docname

.. autoattribute:: parser

Per-document attributes

.. attribute:: 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.

  .. attribute:: current_document.docname
     :type: str

     The document name ('docname') for the current document.

  .. attribute:: current_document.default_role
     :type: str

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

  .. attribute:: current_document.default_domain
     :type: Domain | None

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

  .. attribute:: current_document.highlight_language
     :type: str

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

  .. attribute:: current_document._parser
     :type: Parser | None

     *This attribute is experimental and may be changed without notice.*

     The parser being used to parse the current document.

Utility methods

.. automethod:: doc2path

.. automethod:: relfn2path

.. automethod:: note_dependency

.. automethod:: new_serialno

.. automethod:: note_reread