readthedocs / readthedocs/sphinx-autoapi
Implicit namespace packages do not generate documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 494
- Forks
- 147
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
Hi! Thanks for your work on this package, it really saved me from a lot of autosummary-related misery.
I've noticed a bug: the autoapi_python_use_implicit_namespaces option is fantastic, but it doesn't create a page for implicit namespace packages. If I have a Python project with the following file layout:
- package1/
- package2/
- __init__.py
- module1.py
- package3/
- module2.py
- package4/
- __init__.py
- module3.py
autoapi with autoapi_python_use_implicit_namespaces=True generates the following documentation:
- package1/
- package2/
- index.rst
- module1/
- index.rst
- package3/
- module2/
- index.rst
- package4/
- index.rst
- module3/
- index.rst
In other words, only modules and packages defined with __init__.py files (explicit packages) are documented with an index.rst. Implicit namespace packages, those defined according to PEP420 without __init__.py, are not documented. This leads to Sphinx warnings about their children not being included in any toctree.
According to PEP420, implicit namespace packages are true packages. The user of the library can't tell the difference without digging. I think implicit namespace packages therefore should be documented as true packages, whose members include only their child modules and packages. Ideally they would also have a docstring that suggests that they're implicit namespace packages!
So in my above example, my expected output would be:
- package1/
- index.rst
- package2/
- index.rst
- module1/
- index.rst
- package3/
- index.rst
- module2/
- index.rst
- package4/
- index.rst
- module3/
- index.rst
Thanks!
Contributor guide
No contributing guide indexed for this repository
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 by locating the handling of autoapi_python_use_implicit_namespaces and the code that generates index.rst files. Compare its package detection with the example layout, then verify that implicit namespace packages receive index pages, include their child modules and packages, and no longer produce the reported toctree warnings.
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
- 45/100