diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 4068925c..9c80d70a 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -17,6 +17,10 @@ Features * `#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 `: (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 ^^^^^^^^^ diff --git a/autoapi/extension.py b/autoapi/extension.py index e687ffd3..b29ddb30 100644 --- a/autoapi/extension.py +++ b/autoapi/extension.py @@ -38,6 +38,7 @@ "show-inheritance", "show-module-summary", "special-members", + "imported-members", ] _VIEWCODE_CACHE = {} """Caches a module's parse results for use in viewcode. diff --git a/autoapi/mappers/python/objects.py b/autoapi/mappers/python/objects.py index 9ae7a833..8511172d 100644 --- a/autoapi/mappers/python/objects.py +++ b/autoapi/mappers/python/objects.py @@ -140,8 +140,14 @@ def _should_skip(self): # type: () -> bool 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( diff --git a/docs/maintenance/design.rst b/docs/maintenance/design.rst index e5a6f88e..5e891516 100644 --- a/docs/maintenance/design.rst +++ b/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 diff --git a/docs/reference/config.rst b/docs/reference/config.rst index 44ae2eb0..9c4133f2 100644 --- a/docs/reference/config.rst +++ b/docs/reference/config.rst @@ -91,6 +91,11 @@ Customisation Options and requires `Graphviz `_ 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 diff --git a/tests/python/test_pyintegration.py b/tests/python/test_pyintegration.py index aef98af3..5d38c2a0 100644 --- a/tests/python/test_pyintegration.py +++ b/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"]