Fix imported members being rendered in modules

Fixes #452

autoapi/_mapper.py

@@ -465,7 +465,7 @@ def _hide_yo_kids(self):
                         child["hide"] = True
             elif module["type"] == "module":
                 for child in module["children"]:
-                    if child.get("imported"):
+                    if "original_path" in child:
                         child["hide"] = True
 
     def map(self, options=None):

docs/changes/452.bugfix

@@ -0,0 +1 @@
+Fix imported members being rendered in modules

docs/how_to.rst

@@ -19,29 +19,12 @@ when loaded in Python.
 For example if a function is imported from a submodule into a package
 then that function is documented in both the submodule and the package.
 
-However there are multiple options available for controlling what AutoAPI will document.
-
-
-Connect to the :event:`autoapi-skip-member` event
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The :event:`autoapi-skip-member` event is emitted whenever
-a template has to decide whether a member should be included in the documentation.
-
-For example, to document only packages
--- in other words, to not document submodules --
-you could implement an event handler in your conf.py like the following.
-
-.. code-block:: python
-
-    def skip_submodules(app, what, name, obj, skip, options):
-        if what == "module":
-            skip = True
-        return skip
+.. note::
 
+    The one exception to this rule is that any object imported into a module
+    is not documented by default.
 
-    def setup(sphinx):
-        sphinx.connect("autoapi-skip-member", skip_submodules)
+However there are multiple options available for controlling what AutoAPI will document.
 
 
 Set ``__all__``
@@ -74,11 +57,53 @@ Configure :confval:`autoapi_options`
 
 The :confval:`autoapi_options` configuration value gives some high level control
 over what is documented.
-For example you can hide members that don't have a docstring,
-document private members, and hide magic methods.
+
+For example you could remove ``private-members`` from :confval:`autoapi_options`
+and hide your object definitions in private modules.
+
+.. code-block:: python
+
+    # package/__init__.py
+    from ._submodule import public_function
+
+    # package/_submodule.py
+
+    def public_function():
+        """This public function will be documented only in ``package``."""
+        ...
+
+    def private_function()
+        """This private function won't be documented."""
+        ...
+
+As another example, you could remove ``undoc-members`` from :confval:`autoapi_options`
+and only add docstrings for the modules and other entities that you want to be documented.
+
 See :confval:`autoapi_options` for more information on how to use this option.
 
 
+Connect to the :event:`autoapi-skip-member` event
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :event:`autoapi-skip-member` event is emitted whenever
+a template has to decide whether a member should be included in the documentation.
+
+For example, to document only packages
+-- in other words, to not document submodules --
+you could implement an event handler in your conf.py like the following.
+
+.. code-block:: python
+
+    def skip_submodules(app, what, name, obj, skip, options):
+        if what == "module":
+            skip = True
+        return skip
+
+
+    def setup(sphinx):
+        sphinx.connect("autoapi-skip-member", skip_submodules)
+
+
 Customise the API Documentation Templates
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -95,6 +120,12 @@ You can learn how to customise the templates in the next section;
 How to Customise Layout Through Templates
 -----------------------------------------
 
+.. warning::
+
+    Templates control a lot of behaviour,
+    so customising templates can mean that you lose out on new functionality
+    until you update your customised templates after a new release of AutoAPI.
+
 You can customise the look of the documentation that AutoAPI generates
 by changing the Jinja2 templates that it uses.
 The default templates live in the ``autoapi/templates`` directory of the AutoAPI package.

docs/reference/templates.rst

@@ -62,45 +62,45 @@ that you can reliably access.
 	They can be reliably accessed through templates
 	and :event:`autoapi-skip-member` only.
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonPythonMapper
+.. autoapiclass:: autoapi._objects.PythonPythonMapper
 	:members:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonFunction
+.. autoapiclass:: autoapi._objects.PythonFunction
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonMethod
+.. autoapiclass:: autoapi._objects.PythonMethod
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonProperty
+.. autoapiclass:: autoapi._objects.PythonProperty
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonData
+.. autoapiclass:: autoapi._objects.PythonData
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonAttribute
+.. autoapiclass:: autoapi._objects.PythonAttribute
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.TopLevelPythonPythonMapper
+.. autoapiclass:: autoapi._objects.TopLevelPythonPythonMapper
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonModule
+.. autoapiclass:: autoapi._objects.PythonModule
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonPackage
+.. autoapiclass:: autoapi._objects.PythonPackage
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonClass
+.. autoapiclass:: autoapi._objects.PythonClass
 	:members:
 	:show-inheritance:
 
-.. autoapiclass:: autoapi.mappers.python.objects.PythonException
+.. autoapiclass:: autoapi._objects.PythonException
 	:members:
 	:show-inheritance:

tests/python/pypackagecomplex/complex/_private_module.py

@@ -4,3 +4,8 @@ class PrivateClass(object):
     def public_method():
         """This is public."""
         return 5
+
+
+def imported_function():
+    """A function that gets imported."""
+    return 1

tests/python/pypackagecomplex/complex/submodule.py

@@ -0,0 +1,6 @@
+from ._private_module import imported_function
+
+
+def defined_function():
+    """A function defined in the submodule."""
+    return 1

tests/python/test_pyintegration.py

@@ -746,6 +746,14 @@ def test_hiding_imported_members(builder, parse):
     assert not submodule_file.find(id="complex.subpackage.now_public_function")
 
 
+def test_imports_into_modules_always_hidden(builder, parse):
+    confoverrides = {"autoapi_options": ["members", "undoc-members", "imported-members"]}
+    builder("pypackagecomplex", confoverrides=confoverrides)
+
+    submodule_file = parse("_build/html/autoapi/complex/submodule/index.html")
+    assert not submodule_file.find(id="complex.submodule.imported_function")
+
+
 def test_inherited_members(builder, parse):
     confoverrides = {
         "autoapi_options": ["members", "inherited-members", "undoc-members"],