Build environment API

class sphinx.environment.BuildEnvironment

Attributes

app

Reference to the Sphinx (application) object.

config

Reference to the Config object.

srcdir

Source directory (the directory containing conf.py).

doctreedir

Directory for storing pickled doctrees.

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.

Utility methods

warn(docname, msg, lineno=None)

Emit a warning.

This differs from using app.warn() in that the warning may not be emitted instantly, but collected for emitting all warnings after the update of the environment.

warn_node(msg, node)

Like warn(), but with source information taken from node.

doc2path(docname, base=True, suffix=None)

Return the filename for the document name.

If base is True, return absolute path under self.srcdir. If base is None, return relative path to self.srcdir. If base is a path string, return absolute path under that. If suffix is not None, add it instead of config.source_suffix.

relfn2path(filename, docname=None)

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)

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='')

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

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

note_reread()

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