diff --git a/docs/conf.py b/docs/conf.py index ce51626..2b174d7 100644 --- a/docs/conf.py +++ b/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 = [] diff --git a/docs/usage.rst b/docs/usage.rst index 9946fa3..7ae19b1 100644 --- a/docs/usage.rst +++ b/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 `__ -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 diff --git a/requirements.txt b/requirements.txt index 3233346..45c7f01 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -sphinx>=2.0 +sphinx>=3.0 click>=7.0 docutils diff --git a/sphinx_click/ext.py b/sphinx_click/ext.py index 94bd3a7..f2a2b18 100644 --- a/sphinx_click/ext.py +++ b/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,