diff --git a/CHANGES.rst b/CHANGES.rst index 6c0ca46..a7fdad5 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -4,6 +4,9 @@ Changes in sphinx-automodapi 0.18.0 (unreleased) ------------------- +- Fixed an issue where items defined in ``__all__`` but originally imported + from elsewhere, e.g. a private module, were not documented. [#190] + 0.17.0 (2024-02-22) ------------------- diff --git a/sphinx_automodapi/tests/cases/public_from_private/README.md b/sphinx_automodapi/tests/cases/public_from_private/README.md new file mode 100644 index 0000000..0381ea2 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/README.md @@ -0,0 +1,2 @@ +Importing a class from a private submodule to a public submodule +at the same level of hierarchy in the module. diff --git a/sphinx_automodapi/tests/cases/public_from_private/input/index.rst b/sphinx_automodapi/tests/cases/public_from_private/input/index.rst new file mode 100644 index 0000000..37d01fa --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/input/index.rst @@ -0,0 +1 @@ +.. automodapi:: sphinx_automodapi.tests.example_module.public diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst new file mode 100644 index 0000000..becaa5a --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst @@ -0,0 +1,7 @@ +Camelot +======= + +.. currentmodule:: sphinx_automodapi.tests.example_module.public + +.. autoclass:: Camelot + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst new file mode 100644 index 0000000..bf19304 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst @@ -0,0 +1,7 @@ +Spam +==== + +.. currentmodule:: sphinx_automodapi.tests.example_module.public + +.. autoclass:: Spam + :show-inheritance: diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi new file mode 100644 index 0000000..d285595 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi @@ -0,0 +1,19 @@ + +sphinx_automodapi.tests.example_module.public Module +---------------------------------------------------- + +.. automodule:: sphinx_automodapi.tests.example_module.public + +Classes +^^^^^^^ + +.. automodsumm:: sphinx_automodapi.tests.example_module.public + :classes-only: + :toctree: api + +Class Inheritance Diagram +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automod-diagram:: sphinx_automodapi.tests.example_module.public + :private-bases: + :parts: 1 diff --git a/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm new file mode 100644 index 0000000..7eade32 --- /dev/null +++ b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm @@ -0,0 +1,7 @@ +.. currentmodule:: sphinx_automodapi.tests.example_module.public + +.. autosummary:: + :toctree: api + + Camelot + Spam diff --git a/sphinx_automodapi/tests/example_module/_private.py b/sphinx_automodapi/tests/example_module/_private.py new file mode 100644 index 0000000..d10c9db --- /dev/null +++ b/sphinx_automodapi/tests/example_module/_private.py @@ -0,0 +1,4 @@ +class Camelot: + """ + It's a silly place anyway + """ diff --git a/sphinx_automodapi/tests/example_module/public.py b/sphinx_automodapi/tests/example_module/public.py new file mode 100644 index 0000000..035a9b2 --- /dev/null +++ b/sphinx_automodapi/tests/example_module/public.py @@ -0,0 +1,7 @@ +from ._private import Camelot +from .classes import Spam + +__all__ = [ + 'Camelot', + 'Spam' +] diff --git a/sphinx_automodapi/utils.py b/sphinx_automodapi/utils.py index 1763fcb..38e7be4 100644 --- a/sphinx_automodapi/utils.py +++ b/sphinx_automodapi/utils.py @@ -50,9 +50,11 @@ def find_mod_objs(modname, onlylocals=False, sort=False): modname : str The name of the module to search. onlylocals : bool or list - If True, only attributes that are either members of `modname` OR one of + If `True`, only attributes that are either members of `modname` OR one of its modules or subpackages will be included. If a list, only members of packages in the list are included. If `False`, selection is done. + This option is ignored if a module defines __all__ - in that case, __all__ + is used to determine whether objects are public. Returns ------- @@ -81,7 +83,7 @@ def find_mod_objs(modname, onlylocals=False, sort=False): # Optionally sort the items alphabetically if sort: pkgitems.sort() - + onlylocals = False else: pkgitems = [(k, getattr(mod, k)) for k in dir(mod) if k[0] != "_"] diff --git a/tox.ini b/tox.ini index c320e6b..c0e74f2 100644 --- a/tox.ini +++ b/tox.ini @@ -19,7 +19,7 @@ extras = test: test commands = pip freeze - !cov: pytest --pyargs sphinx_automodapi + !cov: pytest --pyargs sphinx_automodapi {posargs} cov: pytest --pyargs sphinx_automodapi --cov sphinx_automodapi --cov-config={toxinidir}/setup.cfg {posargs} cov: coverage xml -o {toxinidir}/coverage.xml passenv = HOME, WINDIR, LC_ALL, LC_CTYPE, LANG, CC, CI