diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 17:25:40 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 17:25:40 +0000 |
commit | cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch) | |
tree | 18dcde1a8d1f5570a77cd0c361de3b490d02c789 /sphinx/environment/collectors/__init__.py | |
parent | Initial commit. (diff) | |
download | sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip |
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'sphinx/environment/collectors/__init__.py')
-rw-r--r-- | sphinx/environment/collectors/__init__.py | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/sphinx/environment/collectors/__init__.py b/sphinx/environment/collectors/__init__.py new file mode 100644 index 0000000..c7e069a --- /dev/null +++ b/sphinx/environment/collectors/__init__.py @@ -0,0 +1,72 @@ +"""The data collector components for sphinx.environment.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from docutils import nodes + + from sphinx.application import Sphinx + from sphinx.environment import BuildEnvironment + + +class EnvironmentCollector: + """An EnvironmentCollector is a specific data collector from each document. + + It gathers data and stores :py:class:`BuildEnvironment + <sphinx.environment.BuildEnvironment>` as a database. Examples of specific + data would be images, download files, section titles, metadatas, index + entries and toctrees, etc. + """ + + listener_ids: dict[str, int] | None = None + + def enable(self, app: Sphinx) -> None: + assert self.listener_ids is None + self.listener_ids = { + 'doctree-read': app.connect('doctree-read', self.process_doc), + 'env-merge-info': app.connect('env-merge-info', self.merge_other), + 'env-purge-doc': app.connect('env-purge-doc', self.clear_doc), + 'env-get-updated': app.connect('env-get-updated', self.get_updated_docs), + 'env-get-outdated': app.connect('env-get-outdated', self.get_outdated_docs), + } + + def disable(self, app: Sphinx) -> None: + assert self.listener_ids is not None + for listener_id in self.listener_ids.values(): + app.disconnect(listener_id) + self.listener_ids = None + + def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None: + """Remove specified data of a document. + + This method is called on the removal of the document.""" + raise NotImplementedError + + def merge_other(self, app: Sphinx, env: BuildEnvironment, + docnames: set[str], other: BuildEnvironment) -> None: + """Merge in specified data regarding docnames from a different `BuildEnvironment` + object which coming from a subprocess in parallel builds.""" + raise NotImplementedError + + def process_doc(self, app: Sphinx, doctree: nodes.document) -> None: + """Process a document and gather specific data from it. + + This method is called after the document is read.""" + raise NotImplementedError + + def get_updated_docs(self, app: Sphinx, env: BuildEnvironment) -> list[str]: + """Return a list of docnames to re-read. + + This methods is called after reading the whole of documents (experimental). + """ + return [] + + def get_outdated_docs(self, app: Sphinx, env: BuildEnvironment, + added: set[str], changed: set[str], removed: set[str]) -> list[str]: + """Return a list of docnames to re-read. + + This methods is called before reading the documents. + """ + return [] |