Add support for mocking modules

Author: peytondmurray

docs/usage.rst

@@ -59,6 +59,12 @@ Once enabled, *sphinx-click* enables automatic documentation for
    their options and their environment variables using the `Sphinx standard
    domain`_.
 
+*sphinx-click* allows for modules to be mocked out using the same method used by
+`sphinx.ext.autodoc`_. Modules to mock while the documentation is being built
+can be specified using the ``sphinx_click_mock_imports`` config value, if specified.
+Otherwise the value of ``autodoc_mock_imports`` is used, following the behavior
+of ``sphinx.ext.autosummary``. The value of this config option should be a list
+of module names; see `sphinx.ext.autodoc`_ for more information.
 
 .. _cross-referencing:
 
@@ -287,3 +293,4 @@ for more information.
 .. _ref role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
 .. |envvar role| replace:: ``:envvar:``
 .. _envvar role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-envvar
+.. _sphinx.ext.autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports

releasenotes/notes/add-mock-modules-support-d4663c3265eeba5e.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Added support for mocking imported modules during the build process. Mocked
+    modules can either be specified from a ``sphinx_click_mock_imports`` variable,
+    if specified, or by default using ``autodoc_mock_imports``.

sphinx_click/ext.py

@@ -16,6 +16,7 @@
 from sphinx import application
 from sphinx.util import logging
 from sphinx.util import nodes as sphinx_nodes
+from sphinx.ext.autodoc import mock
 
 LOG = logging.getLogger(__name__)
 
@@ -423,7 +424,8 @@ def _load_module(self, module_path: str) -> ty.Union[click.Command, click.Group]
             )
 
         try:
-            mod = __import__(module_name, globals(), locals(), [attr_name])
+            with mock(self.env.config.sphinx_click_mock_imports):
+                mod = __import__(module_name, globals(), locals(), [attr_name])
         except (Exception, SystemExit) as exc:  # noqa
             err_msg = 'Failed to import "{}" from "{}". '.format(attr_name, module_name)
             if isinstance(exc, SystemExit):
@@ -562,6 +564,8 @@ def run(self) -> ty.Iterable[nodes.section]:
 
 
 def setup(app: application.Sphinx) -> ty.Dict[str, ty.Any]:
+    # Need autodoc to support mocking modules
+    app.setup_extension('sphinx.ext.autodoc')
     app.add_directive('click', ClickDirective)
 
     app.add_event("sphinx-click-process-description")
@@ -570,6 +574,9 @@ def setup(app: application.Sphinx) -> ty.Dict[str, ty.Any]:
     app.add_event("sphinx-click-process-arguments")
     app.add_event("sphinx-click-process-envvars")
     app.add_event("sphinx-click-process-epilog")
+    app.add_config_value(
+        'sphinx_click_mock_imports', lambda config: config.autodoc_mock_imports, 'env'
+    )
 
     return {
         'parallel_read_safe': True,

tests/roots/basics/conf.py

@@ -4,3 +4,5 @@
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 extensions = ['sphinx_click']
+
+autodoc_mock_imports = ["fake_dependency"]

tests/roots/basics/greet.py

@@ -1,12 +1,13 @@
 """The greet example taken from the README."""
 
 import click
+import fake_dependency  # Used to test that mocking works
 
 
 @click.group()
 def greet():
     """A sample command group."""
-    pass
+    fake_dependency.do_stuff("hello!")
 
 
 @greet.command()