Added the imported-members AutoAPI option

Closes #204

CHANGELOG.rst

@@ -17,6 +17,10 @@ Features
 * `#203 <https://github.com/readthedocs/sphinx-autoapi/issues/203>`: (Python)
   A class without a docstring inherits one from its parent.
   A methods without a docstring inherits one from the method that it overrides.
+* `#204 <https://github.com/readthedocs/sphinx-autoapi/issues/204>`: (Python)
+  Added the ``imported-members`` AutoAPI option to be able to enable or disable
+  documenting objects imported from the same top-level package or module
+  without needing to override templates.
 
 Bug Fixes
 ^^^^^^^^^

autoapi/extension.py

@@ -38,6 +38,7 @@ _DEFAULT_OPTIONS = [
     "show-inheritance",
     "show-module-summary",
     "special-members",
+    "imported-members",
 ]
 _VIEWCODE_CACHE = {}
 """Caches a module's parse results for use in viewcode.

autoapi/mappers/python/objects.py

@@ -140,8 +140,14 @@ class PythonPythonMapper(PythonMapperBase):
         skip_special_member = (
             self.is_special_member and "special-members" not in self.options
         )
+        skip_imported_member = self.imported and "imported-members" not in self.options
 
-        return skip_undoc_member or skip_private_member or skip_special_member
+        return (
+            skip_undoc_member
+            or skip_private_member
+            or skip_special_member
+            or skip_imported_member
+        )
 
     def _ask_ignore(self, skip):  # type: (bool) -> bool
         ask_result = self.app.emit_firstresult(

docs/maintenance/design.rst

@@ -15,7 +15,6 @@ There are some exceptions to this rule:
   Usually a module is where implementations exist.
   Therefore an import of something is usually for the usage of the implementation,
   and not as something to be accessed publicly.
-  
 
 
 .NET

docs/reference/config.rst

@@ -91,6 +91,11 @@ Customisation Options
 	  and requires `Graphviz <https://graphviz.org/>`_ to be installed.
 	* ``show-module-summary``: Whether to include autosummary directives
 	  in generated module documentation.
+	* ``imported-members``: Display objects imported from the same
+	  top level package or module.
+	  The default module template does not include imported objects,
+	  even with this option enabled.
+	  The default package template does.
 
 
 .. confval:: autoapi_ignore

tests/python/test_pyintegration.py

@@ -367,6 +367,29 @@ def test_hiding_inheritance(builder):
     assert "Bases:" not in example_file
 
 
+def test_hiding_imported_members(builder):
+    confoverrides = {"autoapi_options": ["members", "undoc-members"]}
+    builder("pypackagecomplex", confoverrides=confoverrides)
+
+    subpackage_path = "_build/text/autoapi/complex/subpackage/index.txt"
+    with io.open(subpackage_path, encoding="utf8") as subpackage_handle:
+        subpackage_file = subpackage_handle.read()
+
+    assert "Part of a public resolution chain." not in subpackage_file
+
+    package_path = "_build/text/autoapi/complex/index.txt"
+    with io.open(package_path, encoding="utf8") as package_handle:
+        package_file = package_handle.read()
+
+    assert "Part of a public resolution chain." not in package_file
+
+    submodule_path = "_build/text/autoapi/complex/subpackage/submodule/index.txt"
+    with io.open(submodule_path, encoding="utf8") as submodule_handle:
+        submodule_file = submodule_handle.read()
+
+    assert "A private function made public by import." not in submodule_file
+
+
 def test_inherited_members(builder):
     confoverrides = {
         "autoapi_options": ["members", "inherited-members", "undoc-members"]