diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 306ab811c..e7f641e43 100644 --- a/doc/extdev/appapi.rst +++ b/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 diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst index 50110c2a4..2e735e286 100644 --- a/doc/extdev/logging.rst +++ b/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() diff --git a/sphinx/config.py b/sphinx/config.py index 1b3f51a6e..18da9eb9a 100644 --- a/sphinx/config.py +++ b/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) diff --git a/sphinx/errors.py b/sphinx/errors.py index eef1a157a..28592806a 100644 --- a/sphinx/errors.py +++ b/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 diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index 04bf91830..4835a5755 100644 --- a/sphinx/util/logging.py +++ b/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()