pdoc3 / pdoc3/pdoc

pdoc3 references internal symbols instead of public ones

Open
#228 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
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_function to reference the public type MyInterface
  • the documentation of the arguments of my_function to show type information
  • ideally a link from the type MyInterface in the signature of my_function to the documentation of MyInterface
Actual Behavior
  • the variable MY_VAR is not documented at all
  • the signature of my_function shows the internal type name not the public one (it shows def my_function (iface: pdoc_test._internal.interface.MyInterface) ‑> str) instead of def my_function(iface: pdoc_test.MyInterface) ‑> str
  • the documentation of the arguments and the return value of my_function does 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.