pdoc3 references internal symbols instead of public ones
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 146
- PR merge metrics
- No merged PRs in 30d
Description
I am keeping my python implementation details in a package called _internal and export the methods, classes and variables that are supposed to be the public API by re-exporting them in the __init__.py of the parent package, e.g. like so:
from ._internal.interface import MyInterface
from ._internal.sample import MY_VAR, my_function
__all__ = ['MyInterface', 'MY_VAR', 'my_function']
the signature e.g. of my_function is:
def my_function(iface: MyInterface) -> str:
"""My function doc
Args:
iface: interface parameter doc
Returns:
return value doc
"""
...
Expected Behavior
- all three entities from
__all__to be visible in the documentation - the documentation of
my_functionto reference the public typeMyInterface - the documentation of the arguments of
my_functionto show type information - ideally a link from the type
MyInterfacein the signature ofmy_functionto the documentation ofMyInterface
Actual Behavior
- the variable
MY_VARis not documented at all - the signature of
my_functionshows the internal type name not the public one (it showsdef my_function (iface: pdoc_test._internal.interface.MyInterface) ‑> str)instead ofdef my_function(iface: pdoc_test.MyInterface) ‑> str - the documentation of the arguments and the return value of
my_functiondoes not show any type hint
Steps to Reproduce
I have create a small repo to reproduce at:
https://github.com/Carsten-Leue/pdoc-test
Generated documentation showing the issue is here:
https://carsten-leue.github.io/pdoc-test/pdoc_test/
Additional info
- pdoc version:
0.8.3
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked pdoc-test repository and reproduce the output using the reported pdoc version and the package init.py re-exports shown here. Done means MY_VAR appears, signatures and argument or return documentation use the public names, and MyInterface can link to its generated documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100