mitmproxy / mitmproxy/pdoc

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

Open
#774 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
2.5k
Forks
228
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the behavior with a package init.py that imports functions and a settings dictionary from submodules and lists them in all. Start by tracing how pdoc classifies imported functions versus variables; done means the variable appears with the functions in API Documentation, in all order, while remaining documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.