Add document for utility classes

doc/extdev/index.rst

@@ -94,6 +94,7 @@ APIs used for writing extensions
    nodes
    logging
    i18n
+   utils
 
 Deprecated APIs
 ---------------

doc/extdev/utils.rst

@@ -0,0 +1,19 @@
+Utilities
+=========
+
+Sphinx provides utility classes and functions to develop extensions.
+
+Base classes for components
+---------------------------
+
+These base classes are useful to allow your extensions to obtain Sphinx
+components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily.
+
+.. note:: The subclasses of them might not work with bare docutils because they
+          are strongly coupled with Sphinx.
+
+.. autoclass:: sphinx.transforms.SphinxTransform
+   :members:
+
+.. autoclass:: sphinx.util.docutils.SphinxDirective
+   :members:

sphinx/transforms/__init__.py

@@ -44,35 +44,28 @@ default_substitutions = set([
 
 
 class SphinxTransform(Transform):
-    """
+    """A base class of Transforms.
-    A base class of Transforms.
 
     Compared with ``docutils.transforms.Transform``, this class improves accessibility to
     Sphinx APIs.
-
-    The subclasses can access following objects and functions:
-
-    self.app
-        The application object (:class:`sphinx.application.Sphinx`)
-    self.config
-        The config object (:class:`sphinx.config.Config`)
-    self.env
-        The environment object (:class:`sphinx.environment.BuildEnvironment`)
     """
 
     @property
     def app(self):
         # type: () -> Sphinx
+        """Reference to the :class:`.Sphinx` object."""
         return self.document.settings.env.app
 
     @property
     def env(self):
         # type: () -> BuildEnvironment
+        """Reference to the :class:`.BuildEnvironment` object."""
         return self.document.settings.env
 
     @property
     def config(self):
         # type: () -> Config
+        """Reference to the :class:`.Config` object."""
         return self.document.settings.env.config