From 1775419e667c17b00d7a00a3ef9945d5086ffa45 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 11 Sep 2024 12:41:20 +0100 Subject: [PATCH 1/5] Added regression test for importing a class from a private submodule into a public one --- .../tests/cases/public_from_private/README.md | 2 ++ .../cases/public_from_private/input/index.rst | 1 + ...pi.tests.example_module.public.Camelot.rst | 7 +++++++ .../output/index.rst.automodapi | 19 +++++++++++++++++++ .../output/index.rst.automodsumm | 7 +++++++ .../tests/example_module/_private.py | 4 ++++ .../tests/example_module/public.py | 1 + 7 files changed, 41 insertions(+) create mode 100644 sphinx_automodapi/tests/cases/public_from_private/README.md create mode 100644 sphinx_automodapi/tests/cases/public_from_private/input/index.rst create mode 100644 sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Camelot.rst create mode 100644 sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodapi create mode 100644 sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm create mode 100644 sphinx_automodapi/tests/example_module/_private.py create mode 100644 sphinx_automodapi/tests/example_module/public.py 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/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..6792f70 --- /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 + 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..1d27c5c --- /dev/null +++ b/sphinx_automodapi/tests/example_module/public.py @@ -0,0 +1 @@ +from ._private import Camelot From baa2716c7bf616bda97cc68b7f99c85a5d94e418 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 11 Sep 2024 12:58:58 +0100 Subject: [PATCH 2/5] __all__ should take precedence over onlylocals for determining what is public --- sphinx_automodapi/tests/example_module/public.py | 4 ++++ sphinx_automodapi/utils.py | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/sphinx_automodapi/tests/example_module/public.py b/sphinx_automodapi/tests/example_module/public.py index 1d27c5c..2de6180 100644 --- a/sphinx_automodapi/tests/example_module/public.py +++ b/sphinx_automodapi/tests/example_module/public.py @@ -1 +1,5 @@ from ._private import Camelot + +__all__ = [ + 'Camelot' +] 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] != "_"] From c7e52e156b8bb00eec8a5ee41cdcaa7f80b263ed Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 11 Sep 2024 13:02:35 +0100 Subject: [PATCH 3/5] Added changelog entry --- CHANGES.rst | 3 +++ 1 file changed, 3 insertions(+) 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) ------------------- From 23d4849a92f581813fef248aedf116af14624ee2 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Thu, 12 Sep 2024 10:08:06 +0100 Subject: [PATCH 4/5] Add missing {posargs} in tox.ini --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 76731714765961d3e03ddcb63e1720e9e1a462a5 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Thu, 12 Sep 2024 10:09:24 +0100 Subject: [PATCH 5/5] Include a class imported from a public submodule too --- .../sphinx_automodapi.tests.example_module.public.Spam.rst | 7 +++++++ .../cases/public_from_private/output/index.rst.automodsumm | 2 +- sphinx_automodapi/tests/example_module/public.py | 4 +++- 3 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 sphinx_automodapi/tests/cases/public_from_private/output/api/sphinx_automodapi.tests.example_module.public.Spam.rst 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.automodsumm b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm index 6792f70..7eade32 100644 --- a/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm +++ b/sphinx_automodapi/tests/cases/public_from_private/output/index.rst.automodsumm @@ -4,4 +4,4 @@ :toctree: api Camelot - + Spam diff --git a/sphinx_automodapi/tests/example_module/public.py b/sphinx_automodapi/tests/example_module/public.py index 2de6180..035a9b2 100644 --- a/sphinx_automodapi/tests/example_module/public.py +++ b/sphinx_automodapi/tests/example_module/public.py @@ -1,5 +1,7 @@ from ._private import Camelot +from .classes import Spam __all__ = [ - 'Camelot' + 'Camelot', + 'Spam' ]