Update docs for collectors API

4 files changed, 39 insertions, 1 deletions

diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index f6d21c057..c02e85933 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -359,6 +359,12 @@ package.
 
    .. versionadded:: 1.4
 
+.. method:: Sphinx.add_env_collector(collector)
+
+   Register a environment collector class (refs: :ref:`collector-api`)
+
+   .. versionadded:: 1.6
+
 .. method:: Sphinx.require_sphinx(version)
 
    Compare *version* (which must be a ``major.minor`` version string,
diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst
new file mode 100644
index 000000000..cb4c30bf3
--- /dev/null
+++ b/doc/extdev/collectorapi.rst
@@ -0,0 +1,9 @@
+.. _collector-api:
+
+Environment Collector API
+-------------------------
+
+.. module:: sphinx.environment.collectors
+
+.. autoclass:: EnvironmentCollector
+   :members:
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index 1f3871c21..85172abb6 100644
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -50,6 +50,7 @@ APIs used for writing extensions
    appapi
    envapi
    builderapi
+   collectorapi
    markupapi
    domainapi
    parserapi
diff --git a/sphinx/environment/collectors/__init__.py b/sphinx/environment/collectors/__init__.py
index 3a78d21ba..b8d73ad1f 100644
--- a/sphinx/environment/collectors/__init__.py
+++ b/sphinx/environment/collectors/__init__.py
@@ -19,7 +19,13 @@ if False:
 
 
 class EnvironmentCollector(object):
-    """Base class of data collector for sphinx.environment."""
+    """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 = None  # type: Dict[unicode, int]
 
@@ -43,20 +49,36 @@ class EnvironmentCollector(object):
 
     def clear_doc(self, app, env, docname):
         # type: (Sphinx, BuildEnvironment, unicode) -> None
+        """Remove specified data of a document.
+
+        This method is called on the removal of the document."""
         raise NotImplementedError
 
     def merge_other(self, app, env, docnames, other):
         # type: (Sphinx, BuildEnvironment, Set[unicode], 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, doctree):
         # type: (Sphinx, nodes.Node) -> 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, env):
         # type: (Sphinx, BuildEnvironment) -> List[unicode]
+        """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, env, added, changed, removed):
         # type: (Sphinx, BuildEnvironment, unicode, Set[unicode], Set[unicode], Set[unicode]) -> List[unicode]  # NOQA
+        """Return a list of docnames to re-read.
+
+        This methods is called before reading the documents.
+        """
         return []