Skip to content

Commit 40928e2

Browse files
committed
Fix imported members being rendered in modules
Fixes #452
1 parent 8001fbd commit 40928e2

File tree

7 files changed

+88
-35
lines changed

7 files changed

+88
-35
lines changed

autoapi/_mapper.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -465,7 +465,7 @@ def _hide_yo_kids(self):
465465
child["hide"] = True
466466
elif module["type"] == "module":
467467
for child in module["children"]:
468-
if child.get("imported"):
468+
if "original_path" in child:
469469
child["hide"] = True
470470

471471
def map(self, options=None):

docs/changes/452.bugfix

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Fix imported members being rendered in modules

docs/how_to.rst

Lines changed: 54 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -19,29 +19,12 @@ when loaded in Python.
1919
For example if a function is imported from a submodule into a package
2020
then that function is documented in both the submodule and the package.
2121

22-
However there are multiple options available for controlling what AutoAPI will document.
23-
24-
25-
Connect to the :event:`autoapi-skip-member` event
26-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
27-
28-
The :event:`autoapi-skip-member` event is emitted whenever
29-
a template has to decide whether a member should be included in the documentation.
30-
31-
For example, to document only packages
32-
-- in other words, to not document submodules --
33-
you could implement an event handler in your conf.py like the following.
34-
35-
.. code-block:: python
36-
37-
def skip_submodules(app, what, name, obj, skip, options):
38-
if what == "module":
39-
skip = True
40-
return skip
22+
.. note::
4123

24+
The one exception to this rule is that any object imported into a module
25+
is not documented by default.
4226

43-
def setup(sphinx):
44-
sphinx.connect("autoapi-skip-member", skip_submodules)
27+
However there are multiple options available for controlling what AutoAPI will document.
4528

4629

4730
Set ``__all__``
@@ -74,11 +57,53 @@ Configure :confval:`autoapi_options`
7457

7558
The :confval:`autoapi_options` configuration value gives some high level control
7659
over what is documented.
77-
For example you can hide members that don't have a docstring,
78-
document private members, and hide magic methods.
60+
61+
For example you could remove ``private-members`` from :confval:`autoapi_options`
62+
and hide your object definitions in private modules.
63+
64+
.. code-block:: python
65+
66+
# package/__init__.py
67+
from ._submodule import public_function
68+
69+
# package/_submodule.py
70+
71+
def public_function():
72+
"""This public function will be documented only in ``package``."""
73+
...
74+
75+
def private_function()
76+
"""This private function won't be documented."""
77+
...
78+
79+
As another example, you could remove ``undoc-members`` from :confval:`autoapi_options`
80+
and only add docstrings for the modules and other entities that you want to be documented.
81+
7982
See :confval:`autoapi_options` for more information on how to use this option.
8083

8184

85+
Connect to the :event:`autoapi-skip-member` event
86+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
87+
88+
The :event:`autoapi-skip-member` event is emitted whenever
89+
a template has to decide whether a member should be included in the documentation.
90+
91+
For example, to document only packages
92+
-- in other words, to not document submodules --
93+
you could implement an event handler in your conf.py like the following.
94+
95+
.. code-block:: python
96+
97+
def skip_submodules(app, what, name, obj, skip, options):
98+
if what == "module":
99+
skip = True
100+
return skip
101+
102+
103+
def setup(sphinx):
104+
sphinx.connect("autoapi-skip-member", skip_submodules)
105+
106+
82107
Customise the API Documentation Templates
83108
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
84109

@@ -95,6 +120,12 @@ You can learn how to customise the templates in the next section;
95120
How to Customise Layout Through Templates
96121
-----------------------------------------
97122

123+
.. warning::
124+
125+
Templates control a lot of behaviour,
126+
so customising templates can mean that you lose out on new functionality
127+
until you update your customised templates after a new release of AutoAPI.
128+
98129
You can customise the look of the documentation that AutoAPI generates
99130
by changing the Jinja2 templates that it uses.
100131
The default templates live in the ``autoapi/templates`` directory of the AutoAPI package.

docs/reference/templates.rst

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -62,45 +62,45 @@ that you can reliably access.
6262
They can be reliably accessed through templates
6363
and :event:`autoapi-skip-member` only.
6464

65-
.. autoapiclass:: autoapi.mappers.python.objects.PythonPythonMapper
65+
.. autoapiclass:: autoapi._objects.PythonPythonMapper
6666
:members:
6767

68-
.. autoapiclass:: autoapi.mappers.python.objects.PythonFunction
68+
.. autoapiclass:: autoapi._objects.PythonFunction
6969
:members:
7070
:show-inheritance:
7171

72-
.. autoapiclass:: autoapi.mappers.python.objects.PythonMethod
72+
.. autoapiclass:: autoapi._objects.PythonMethod
7373
:members:
7474
:show-inheritance:
7575

76-
.. autoapiclass:: autoapi.mappers.python.objects.PythonProperty
76+
.. autoapiclass:: autoapi._objects.PythonProperty
7777
:members:
7878
:show-inheritance:
7979

80-
.. autoapiclass:: autoapi.mappers.python.objects.PythonData
80+
.. autoapiclass:: autoapi._objects.PythonData
8181
:members:
8282
:show-inheritance:
8383

84-
.. autoapiclass:: autoapi.mappers.python.objects.PythonAttribute
84+
.. autoapiclass:: autoapi._objects.PythonAttribute
8585
:members:
8686
:show-inheritance:
8787

88-
.. autoapiclass:: autoapi.mappers.python.objects.TopLevelPythonPythonMapper
88+
.. autoapiclass:: autoapi._objects.TopLevelPythonPythonMapper
8989
:members:
9090
:show-inheritance:
9191

92-
.. autoapiclass:: autoapi.mappers.python.objects.PythonModule
92+
.. autoapiclass:: autoapi._objects.PythonModule
9393
:members:
9494
:show-inheritance:
9595

96-
.. autoapiclass:: autoapi.mappers.python.objects.PythonPackage
96+
.. autoapiclass:: autoapi._objects.PythonPackage
9797
:members:
9898
:show-inheritance:
9999

100-
.. autoapiclass:: autoapi.mappers.python.objects.PythonClass
100+
.. autoapiclass:: autoapi._objects.PythonClass
101101
:members:
102102
:show-inheritance:
103103

104-
.. autoapiclass:: autoapi.mappers.python.objects.PythonException
104+
.. autoapiclass:: autoapi._objects.PythonException
105105
:members:
106106
:show-inheritance:

tests/python/pypackagecomplex/complex/_private_module.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,8 @@ class PrivateClass(object):
44
def public_method():
55
"""This is public."""
66
return 5
7+
8+
9+
def imported_function():
10+
"""A function that gets imported."""
11+
return 1
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
from ._private_module import imported_function
2+
3+
4+
def defined_function():
5+
"""A function defined in the submodule."""
6+
return 1

tests/python/test_pyintegration.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -746,6 +746,16 @@ def test_hiding_imported_members(builder, parse):
746746
assert not submodule_file.find(id="complex.subpackage.now_public_function")
747747

748748

749+
def test_imports_into_modules_always_hidden(builder, parse):
750+
confoverrides = {
751+
"autoapi_options": ["members", "undoc-members", "imported-members"]
752+
}
753+
builder("pypackagecomplex", confoverrides=confoverrides)
754+
755+
submodule_file = parse("_build/html/autoapi/complex/submodule/index.html")
756+
assert not submodule_file.find(id="complex.submodule.imported_function")
757+
758+
749759
def test_inherited_members(builder, parse):
750760
confoverrides = {
751761
"autoapi_options": ["members", "inherited-members", "undoc-members"],

0 commit comments

Comments
 (0)