diff --git a/docs/usage.rst b/docs/usage.rst index 5d14d11..7badd4e 100644 --- a/docs/usage.rst +++ b/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 diff --git a/releasenotes/notes/add-mock-modules-support-d4663c3265eeba5e.yaml b/releasenotes/notes/add-mock-modules-support-d4663c3265eeba5e.yaml new file mode 100644 index 0000000..5a541ac --- /dev/null +++ b/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``. diff --git a/sphinx_click/ext.py b/sphinx_click/ext.py index 158c2bc..a6ec3f5 100644 --- a/sphinx_click/ext.py +++ b/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, diff --git a/tests/roots/basics/conf.py b/tests/roots/basics/conf.py index 49d78f3..8151a5d 100644 --- a/tests/roots/basics/conf.py +++ b/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"] diff --git a/tests/roots/basics/greet.py b/tests/roots/basics/greet.py index 8981828..204c55c 100644 --- a/tests/roots/basics/greet.py +++ b/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()