Stub file information doesn't seem to be included from `_lib.pyi`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
Package setup
We have some internal namespace package written in Rust & PyO3.
It's organized like this:
pyproject.toml
uv.lock
tests/
[...]
src/
[internal namespace]/
[pkg name]/
__init__.py
py.typed
_lib.so
_lib.pyi
_lib.so is the shared library built from our Rust code. In our __init__.py, we reference this:
$ cat __init__.py
from ._lib import [ClassA, ClassB, ...]
__all__ = [
"[ClassA]",
"[ClassB]",
...
]
Problem description
When I now create documentation by calling pdoc [namespace].[pkgname], I'm given this function documentation for example:
(ignore the slightly broken formatting of the docstring, this is because we haven't standardized docstring formats yet 😅 )
As you can see, it contains function signature defaults, all parameters and the docstring. But it entirely misses typing information that is in _lib.pyi.
When I create documentation with pdoc [namespace].[pkgname]._lib, I do see information from the stub file though!
But now, the documentation is limited purely to the _lib submodule. Is there a way to create documentation of the entire package, but also correctly discovering stub files automatically?
System Information
$ pdoc --version
pdoc: 15.0.1
Python: 3.11.9
Platform: Linux-6.13.7-1-MANJARO-x86_64-with-glibc2.41
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
Compare the package-level output from pdoc [namespace].[pkgname] with the output for [namespace].[pkgname]._lib, focusing on init.py and _lib.pyi. Trace how stub information is discovered for the submodule and determine what package-level behavior should include the typing information. Done means documenting the package automatically includes the relevant information from _lib.pyi.
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