Add support for mocking of modules

docs/conf.py

@@ -2,87 +2,41 @@
 #
 # sphinx-click documentation build configuration file
 
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-needs_sphinx = '1.5'
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx_click"]
+extensions = ['sphinx_click']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
-
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
-project = u'sphinx-click'
-copyright = u'2017, Stephen Finucane'
-author = u'Stephen Finucane'
+project = 'sphinx-click'
+copyright = '2017-, Stephen Finucane'
+author = 'Stephen Finucane'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u''
+version = ''
 # The full version, including alpha/beta/rc tags.
-release = u''
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
+release = ''
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'alabaster'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = []

docs/usage.rst

@@ -65,6 +65,7 @@ Once enabled, *sphinx-click* enables automatic documentation for
 .. |click.core.BaseCommand| replace:: ``click.core.BaseCommand``
 .. _click.core.BaseCommand: http://click.pocoo.org/6/api/#click.BaseCommand
 
+
 Example
 -------
 
@@ -203,8 +204,32 @@ the application:
 
 assuming the group or command in ``git.git`` is named ``cli``.
 
-Refer to `issue #2 <https://github.com/click-contrib/sphinx-click/issues/2>`__
-for more information.
+Refer to `issue #2`__ for more information.
+
+.. __: https://github.com/click-contrib/sphinx-click/issues/2
+
+
+Mocking missing modules
+-----------------------
+
+.. versionadded:: 3.1.0
+
+.. important::
+
+    This is considered a "power user" feature and should not be used unless
+    necessary. Where possible, all dependencies should be installed.
+
+In some cases, it's simply not possible to install all dependencies for an
+application you wish to document. This is particularly true for dependencies
+that require C extensions or have other non-Python requirements. In these
+cases, you can add the offending module(s) to ``click_mock_imports`` value in
+your ``conf.py`` file. All modules listed in here will be automatically mocked
+out using `unittest.mock`_ module.
+
+Refer to `issue #86`__ for more information.
+
+.. __: https://github.com/click-contrib/sphinx-click/issues/86
 
 .. |CommandCollection| replace:: :code:`CommandCollection`
 .. _CommandCollection: https://click.palletsprojects.com/en/7.x/api/#click.CommandCollection
+.. _unittest.mock: https://docs.python.org/3/library/unittest.mock.html

requirements.txt

@@ -1,3 +1,3 @@
-sphinx>=2.0
+sphinx>=3.0
 click>=7.0
 docutils

sphinx_click/ext.py

@@ -1,5 +1,7 @@
 import re
 import traceback
+import typing as ty
+from unittest import mock
 import warnings
 
 import click
@@ -381,8 +383,12 @@ def _load_module(self, module_path):
                 '"{}" is not of format "module:parser"'.format(module_path)
             )
 
+        mocked_modules = {
+            m: mock.MagicMock() for m in self.env.config.click_mock_imports
+        }
         try:
-            mod = __import__(module_name, globals(), locals(), [attr_name])
+            with mock.patch.dict('sys.modules', **mocked_modules):
+                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):
@@ -511,6 +517,7 @@ def run(self):
 
 def setup(app):
     app.add_directive('click', ClickDirective)
+    app.add_config_value('click_mock_imports', [], 'html', ty.List[str])
 
     return {
         'parallel_read_safe': True,