mitmproxy / mitmproxy/pdoc

Not showing docs when PyO3 registers a struct with a different name

Open
#830 2 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

My PyO3 module exposes a Rust struct in two places:

# mylib.SyncConn
m.add_class::<SyncConn>()?;

# mylib.sync.Conn
let sync = PyModule::new(py, "sync")?;
sync.add("Conn", py.get_type::<SyncConn>())?;
m.add_submodule(&sync)?;

pdoc correctly shows the class members of SyncConn not sync.Conn:

Image

As a workaround, I manually assigned an instance of pdoc.doc.Class to the other.
This works if I want to show the full class members in both places, but if I want to customize them differently, I cannot deepcopy pdoc.doc.Class.

all_modules["pyro_mysql.sync"].members["Conn"] = copy.deepcopy(
        all_modules["pyro_mysql"].members["SyncConn"]
    )

all_modules["pyro_mysql"].members[
    "SyncConn"
].docstring = "See `pyro_mysql.sync.Conn`."
all_modules["pyro_mysql"].members["SyncConn"].own_members = []
all_modules["pyro_mysql"].members["SyncConn"].methods = []
all_modules["pyro_mysql"].members["SyncConn"].staticmembers = []
all_modules["pyro_mysql"].members["SyncConn"].classmembers = []
System Information

pdoc: 15.0.4
Python: 3.14.0rc2

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 issue with the PyO3 module layout shown, then inspect pdoc.doc.Class and the module-member handling for aliases. Confirm how SyncConn and sync.Conn are represented, and make the documentation render correctly for both names while allowing their members or docstrings to differ; add a regression test if the project’s existing tests cover this behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.