Merge pull request #4278 from stephenfin/doc-restructure

Doc restructure

doc/extdev/appapi.rst

@@ -686,16 +686,9 @@ Use this to adapt your extension to API changes in Sphinx.
 The Config object
 -----------------
 
-.. module:: sphinx.config
+.. currentmodule:: sphinx.config
 
-.. class:: Config
-
-   The config object makes the values of all config values available as
-   attributes.
-
-   It is available as the ``config`` attribute on the application and
-   environment objects.  For example, to get the value of :confval:`language`,
-   use either ``app.config.language`` or ``env.config.language``.
+.. autoclass:: Config
 
 
 .. _template-bridge:
@@ -716,38 +709,12 @@ Exceptions
 
 .. module:: sphinx.errors
 
-.. exception:: SphinxError
+.. autoexception:: SphinxError
 
-   This is the base class for "nice" exceptions.  When such an exception is
-   raised, Sphinx will abort the build and present the exception category and
-   message to the user.
+.. autoexception:: ConfigError
 
-   Extensions are encouraged to derive from this exception for their custom
-   errors.
+.. autoexception:: ExtensionError
 
-   Exceptions *not* derived from :exc:`SphinxError` are treated as unexpected
-   and shown to the user with a part of the traceback (and the full traceback
-   saved in a temporary file).
+.. autoexception:: ThemeError
 
-   .. attribute:: category
-
-      Description of the exception "category", used in converting the exception
-      to a string ("category: message").  Should be set accordingly in
-      subclasses.
-
-.. exception:: ConfigError
-
-   Used for erroneous values or nonsensical combinations of configuration
-   values.
-
-.. exception:: ExtensionError
-
-   Used for errors in setting up extensions.
-
-.. exception:: ThemeError
-
-   Used for errors to do with themes.
-
-.. exception:: VersionRequirementError
-
-   Raised when the docs require a higher Sphinx version than the current one.
+.. autoexception:: VersionRequirementError

doc/extdev/logging.rst

@@ -3,18 +3,11 @@
 Logging API
 ===========
 
-.. function:: sphinx.util.logging.getLogger(name)
+.. currentmodule:: sphinx.util.logging
 
-   Returns a logger wrapped by :class:`SphinxLoggerAdapter` with the specified *name*.
+.. autofunction:: getLogger(name)
 
-   Example usage::
-
-     from sphinx.util import logging  # Load on top of python's logging module
-
-     logger = logging.getLogger(__name__)
-     logger.info('Hello, this is an extension!')
-
-.. class:: SphinxLoggerAdapter(logging.LoggerAdapter)
+.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
 
    .. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs)
    .. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs)
@@ -62,16 +55,6 @@ Logging API
         colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``.
         The others are not colored.
 
-.. function:: pending_logging()
+.. autofunction:: pending_logging()
 
-   Marks all logs as pending::
-
-     with pending_logging():
-       logger.warning('Warning message!')  # not flushed yet
-       some_long_process()
-
-     # the warning is flushed here
-
-.. function:: pending_warnings()
-
-   Marks warning logs as pending.  Similar to :func:`pending_logging`.
+.. autofunction:: pending_warnings()

sphinx/config.py

@@ -78,8 +78,15 @@ if PY2:
 
 
 class Config(object):
-    """
-    Configuration file abstraction.
+    """Configuration file abstraction.
+
+    The config object makes the values of all config values available as
+    attributes.
+
+    It is exposed via the :py:attr:`sphinx.application.Application.config` and
+    :py:attr:`sphinx.environment.Environment.config` attributes. For example,
+    to get the value of :confval:`language`, use either ``app.config.language``
+    or ``env.config.language``.
     """
 
     # the values are: (default, what needs to be rebuilt if changed)

sphinx/errors.py

@@ -16,20 +16,35 @@ if False:
 
 
 class SphinxError(Exception):
-    """
-    Base class for Sphinx errors that are shown to the user in a nicer
-    way than normal exceptions.
+    """Base class for Sphinx errors.
+
+    This is the base class for "nice" exceptions.  When such an exception is
+    raised, Sphinx will abort the build and present the exception category and
+    message to the user.
+
+    Extensions are encouraged to derive from this exception for their custom
+    errors.
+
+    Exceptions *not* derived from :exc:`SphinxError` are treated as unexpected
+    and shown to the user with a part of the traceback (and the full traceback
+    saved in a temporary file).
+
+    .. attribute:: category
+
+       Description of the exception "category", used in converting the
+       exception to a string ("category: message").  Should be set accordingly
+       in subclasses.
     """
     category = 'Sphinx error'
 
 
 class SphinxWarning(SphinxError):
-    """Raised for warnings if warnings are treated as errors."""
+    """Warning, treated as error."""
     category = 'Warning, treated as error'
 
 
 class ExtensionError(SphinxError):
-    """Raised if something's wrong with the configuration."""
+    """Extension error."""
     category = 'Extension error'
 
     def __init__(self, message, orig_exc=None):
@@ -53,27 +68,22 @@ class ExtensionError(SphinxError):
 
 
 class ConfigError(SphinxError):
+    """Configuration error."""
     category = 'Configuration error'
 
 
 class ThemeError(SphinxError):
+    """Theme error."""
     category = 'Theme error'
 
 
 class VersionRequirementError(SphinxError):
+    """Incompatible Sphinx version error."""
     category = 'Sphinx version error'
 
 
-class PycodeError(Exception):
-    def __str__(self):
-        # type: () -> str
-        res = self.args[0]
-        if len(self.args) > 1:
-            res += ' (exception was: %r)' % self.args[1]
-        return res
-
-
 class SphinxParallelError(SphinxError):
+    """Sphinx parallel build error."""
 
     category = 'Sphinx parallel build error'
 
@@ -85,3 +95,14 @@ class SphinxParallelError(SphinxError):
     def __str__(self):
         # type: () -> str
         return self.message
+
+
+class PycodeError(Exception):
+    """Pycode Python source code analyser error."""
+
+    def __str__(self):
+        # type: () -> str
+        res = self.args[0]
+        if len(self.args) > 1:
+            res += ' (exception was: %r)' % self.args[1]
+        return res

sphinx/util/logging.py

@@ -60,11 +60,18 @@ COLOR_MAP.update({
 
 def getLogger(name):
     # type: (str) -> SphinxLoggerAdapter
-    """Get logger wrapped by SphinxLoggerAdapter.
+    """Get logger wrapped by :class:`sphinx.util.logging.SphinxLoggerAdapter`.
 
     Sphinx logger always uses ``sphinx.*`` namesapce to be independent from
-    settings of root logger.  It enables to log stably even if 3rd party
-    extension or imported application resets logger settings.
+    settings of root logger.  It ensure logging is consistent even if a
+    third-party extension or imported application resets logger settings.
+
+    Example usage::
+
+        >>> from sphinx.utils import logging
+        >>> logger = logging.getLogger(__name__)
+        >>> logger.info('Hello, this is an extension!')
+        Hello, this is an extension!
     """
     # add sphinx prefix to name forcely
     logger = logging.getLogger(NAMESPACE + '.' + name)
@@ -217,7 +224,10 @@ class MemoryHandler(logging.handlers.BufferingHandler):
 @contextmanager
 def pending_warnings():
     # type: () -> Generator
-    """contextmanager to pend logging warnings temporary."""
+    """Contextmanager to pend logging warnings temporary.
+
+    Similar to :func:`pending_logging`.
+    """
     logger = logging.getLogger(NAMESPACE)
     memhandler = MemoryHandler()
     memhandler.setLevel(logging.WARNING)
@@ -243,7 +253,16 @@ def pending_warnings():
 @contextmanager
 def pending_logging():
     # type: () -> Generator
-    """contextmanager to pend logging all logs temporary."""
+    """Contextmanager to pend logging all logs temporary.
+
+    For example::
+
+        >>> with pending_logging():
+        >>>     logger.warning('Warning message!')  # not flushed yet
+        >>>     some_long_process()
+        >>>
+        Warning message!  # the warning is flushed here
+    """
     logger = logging.getLogger(NAMESPACE)
     memhandler = MemoryHandler()