sphinx-doc / sphinx-doc/sphinx
Namespaces packages more than one level deep are not rendered correctly using autodoc
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
When using a python project with native namespace, as per documentation https://packaging.python.org/namespace_packages, but with an extra namespace level like:
setup.py
setup.cfg
docs/
example_package/
# No __init__.py here.
middle_package/
# No __init__.py here.
subpackage_a/
# Sub-packages have __init__.py.
__init__.py
test_a.py
When running:
sphinx-apidoc --implicit-namespaces --force -o docs/ ./example_package/
$(MAKE) -C docs html
sphinx-apidox is not putting the packages into the toc in the docs as expected.
Giving a consistency fault in the sphinx-builder:
checking consistency... ./example_pkg/docs/example_package.middle_package.rst: WARNING: document isn't included in any toctree
The output from sphinx-apidoc to example_package.rst:
example\_package namespace
==========================
.. py:module:: example_package
where the expected output is:
example\_package.middle\_package namespace
==========================================
.. py:module:: example_package
Subpackages
-----------
.. toctree::
:maxdepth: 4
example_package.middle_package
How to Reproduce
get project from github
git clone https://github.com/michiel007/example_pkg
cd example_pkg
create and setup virtual environment
python -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
generate documentation
make docs
Expected behavior
No response
Your project
https://github.com/michiel007/example_pkg
Screenshots
No response
OS
ubuntu 20.04 LTS
Python version
3.8
Sphinx version
4.2.0
Sphinx extensions
sphinx.ext.autodoc
Extra tools
browser (optional)
Additional context
No response
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
Reproduce the issue with the documented sphinx-apidoc --implicit-namespaces command and the example_pkg project, then inspect the generated example_package.rst and example_package.middle_package.rst files. Trace how nested namespace packages are added to the generated toctree; done means the middle package is included and the Sphinx consistency warning no longer appears.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100