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/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()