mock: little changes, changelog and versionadded

CHANGES

@@ -18,6 +18,9 @@ New features
 * PR#202: Allow "." and "~" prefixed references in ``:param:`` doc fields
   for Python.
 
+* PR#184: Add :confval:`autodoc_mock_imports`, allowing to mock imports of
+  external modules that need not be present when autodocumenting.
+
 * #925: Allow list-typed config values to be provided on the command line,
   like ``-D key=val1,val2``.
 

doc/ext/autodoc.rst

@@ -199,6 +199,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      import errors to halt the building process when some external dependencies
      are not importable at build time.
 
+     .. versionadded:: 1.3
+
 
 .. rst:directive:: autofunction
                    autodata
@@ -345,6 +347,8 @@ There are also new config values that you can set:
    some external dependencies are not met at build time and break the building
    process.
 
+   .. versionadded:: 1.3
+
 
 Docstring preprocessing
 -----------------------

sphinx/ext/autodoc.py

@@ -71,6 +71,7 @@ class Options(dict):
 
 
 class _MockModule(object):
+    """Used by autodoc_mock_imports."""
     def __init__(self, *args, **kwargs):
         pass
 
@@ -89,6 +90,14 @@ class _MockModule(object):
         else:
             return _MockModule()
 
+def mock_import(modname):
+    if '.' in modname:
+        pkg, _n, mods = modname.rpartition('.')
+        mock_import(pkg)
+    mod = _MockModule()
+    sys.modules[modname] = mod
+    return mod
+
 
 ALL = object()
 INSTANCEATTR = object()
@@ -353,7 +362,8 @@ class Documenter(object):
         try:
             dbg('[autodoc] import %s', self.modname)
             for modname in self.env.config.autodoc_mock_imports:
-                self._mock_import(modname)
+                dbg('[autodoc] adding a mock module %s!', self.modname)
+                mock_import(modname)
             __import__(self.modname)
             parent = None
             obj = self.module = sys.modules[self.modname]
@@ -383,15 +393,6 @@ class Documenter(object):
             self.env.note_reread()
             return False
 
-    def _mock_import(self, modname):
-        if '.' in modname:
-            pkg, _n, mods = modname.rpartition('.')
-            self._mock_import(pkg)
-        mod = _MockModule()
-        sys.modules[modname] = mod
-        return mod
-
-
     def get_real_modname(self):
         """Get the real module name of an object to document.