Submodule functions in __all__ get correctly hoisted to top-level docs, but not submodule variables

[michael1006]

Problem Description

I have a package with lots of modules within. In the package __init__.py, I define __all__ with all of the functions I want to expose to the user. This works great, and pdoc puts all the functions in a single list under "API Documentation". Exactly what I want.

The problem is that I also include a single settings dictionary variable imported from a submodule, alongside all the functions imported from submodules. I include that in __all__, but for some reason pdoc then creates a separate "Submodules" section of the documentation that lists "settings" underneath, that links to a separate page, that documents the variable.

I absolutely want to include the variable documentation -- I just want it to be listed next to the functions in the order it is specified in __all__. I don't see any reason for forcing variables that aren't functions into submodule listings, so this seems to be a bug?

Expected behavior: non-function variables in __all__ get included alongside function variables Actual behavior: non-function variables in __all__ are still being documented as belonging to submodules

System Information

pdoc: 15.0.1 Python: 3.12.8 Platform: macOS-15.2-arm64-arm-64bit

[michael1006]

Oh, and perhaps a follow-up/related bug -- if I pass !pkgname. to pdoc to suppress all submodules (so I can document the settings in my readme instead), it still shows a big "Submodules" section in the table of contents, but it's empty. Seems like if there are no submodules, then there's shouldn't be any submodules section?

[mhils]

I absolutely want to include the variable documentation -- I just want it to be listed next to the functions in the order it is specified in __all__. I don't see any reason for forcing variables that aren't functions into submodule listings, so this seems to be a bug?

This needs a reproducer.

Oh, and perhaps a follow-up/related bug -- if I pass !pkgname. to pdoc to suppress all submodules (so I can document the settings in my readme instead), it still shows a big "Submodules" section in the table of contents, but it's empty. Seems like if there are no submodules, then there's shouldn't be any submodules section?

Agreed, that's a bug in the template. Contributions welcome!

[michael1006]

This needs a reproducer.

Attached.

2025-02-10 - pdoc variable.zip

Results look like:

Agreed, that's a bug in the template. Contributions welcome!

I'm not sure. When I change the command in the reproducer to:

pdoc ../testpkg !testpkg. -o ./generated

And then directly under line 46 of module.html.jinja2 where it says {% if module.submodules %} I add:

{{ module.submodules }}

Then it outputs:

[<module testpkg.config <var config = {'a': 0, 'b': 1}> >]

So the bug is possibly that it is passing a submodule in the first place when there should be none?

Alternatively, you only print "public" submodules:

{% for submodule in module.submodules if is_public(submodule) | trim %}
    <li>{{ submodule.taken_from | link(text=submodule.name) }}</li>
{% endfor %}

So perhaps {% if module.submodules %} needs to be replaced with a conditional that tests not just for submodules, but if there are public submodules?

I don't have the broader understanding of pdoc to know which you intend.

[mhils]

So the bug is possibly that it is passing a submodule in the first place when there should be none?

yeah, it shouldn't be passed in the first place, it should be filtered out here: https://github.com/mitmproxy/pdoc/blob/49915832d6c018339b9d256a16ae3ae57fa48076/pdoc/extract.py#L50-L55

Maybe some bug in the Module.submodules implementation?