8000 Add support for mocking modules · click-contrib/sphinx-click@5a547d0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 5a547d0

Browse files
peytondmurraystephenfin
peytondmurray
authored and
stephenfin
committed
Add support for mocking modules
1 parent 0ba0d2c commit 5a547d0

File tree

5 files changed

+25
-2
lines changed

5 files changed

+25
-2
lines changed

‎docs/usage.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,12 @@ Once enabled, *sphinx-click* enables automatic documentation for
5959
their options and their environment variables using the `Sphinx standard
6060
domain`_.
6161

62+
*sphinx-click* allows for modules to be mocked out using the same method used by
63+
`sphinx.ext.autodoc`_. Modules to mock while the documentation is being built
64+
can be specified using the ``sphinx_click_mock_imports`` config value, if specified.
65+
Otherwise the value of ``autodoc_mock_imports`` is used, following the behavior
66+
of ``sphinx.ext.autosummary``. The value of this config option should be a list
67+
of module names; see `sphinx.ext.autodoc`_ for more information.
6268

6369
.. _cross-referencing:
6470

@@ -287,3 +293,4 @@ for more information.
287293
.. _ref role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
288294
.. |envvar role| replace:: ``:envvar:``
289295
.. _envvar role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-envvar
296+
.. _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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
features:
3+
- |
4+
Added support for mocking imported modules during the build process. Mocked
5+
modules can either be specified from a ``sphinx_click_mock_imports`` variable,
6+
if specified, or by default using ``autodoc_mock_imports``.

‎sphinx_click/ext.py

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
from sphinx import application
1717
from sphinx.util import logging
1818
from sphinx.util import nodes as sphinx_nodes
19+
from sphinx.ext.autodoc import mock
1920

2021
LOG = logging.getLogger(__name__)
2122

@@ -423,7 +424,8 @@ def _load_module(self, module_path: str) -> ty.Union[click.Command, click.Group]
423424
)
424425

425426
try:
426-
mod = __import__(module_name, globals(), locals(), [attr_name])
427+
with mock(self.env.config.sphinx_click_mock_imports):
428+
mod = __import__(module_name, globals(), locals(), [attr_name])
427429
except (Exception, SystemExit) as exc: # noqa
428430
err_msg = 'Failed to import "{}" from "{}". '.format(attr_name, module_name)
429431
if isinstance(exc, SystemExit):
@@ -562,6 +564,8 @@ def run(self) -> ty.Iterable[nodes.section]:
562564

563565

564566
def setup(app: application.Sphinx) -> ty.Dict[str, ty.Any]:
567+
# Need autodoc to support mocking modules
568+
app.setup_extension('sphinx.ext.autodoc')
565569
app.add_directive('click', ClickDirective)
566570

567571
app.add_event("sphinx-click-process-description")
@@ -570,6 +574,9 @@ def setup(app: application.Sphinx) -> ty.Dict[str, ty.Any]:
570574
app.add_event("sphinx-click-process-arguments")
571575
app.add_event("sphinx-click-process-envvars")
572576
app.add_event("sphinx-click-process-epilog")
577+
app.add_config_value(
578+
'sphinx_click_mock_imports', lambda config: config.autodoc_mock_imports, 'env'
579+
)
573580

574581
return {
575582
'parallel_read_safe': True,

‎tests/roots/basics/conf.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,5 @@
44
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
55

66
extensions = ['sphinx_click']
7+
8+
autodoc_mock_imports = ["fake_dependency"]

‎tests/roots/basics/greet.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
"""The greet example taken from the README."""
22

33
import click
4+
import fake_dependency # Used to test that mocking works
45

56

67
@click.group()
78
def greet():
89
"""A sample command group."""
9-
pass
10+
fake_dependency.do_stuff("hello!")
1011

1112

1213
@greet.command()

0 commit comments

Comments
 (0)
0