sphinx-doc / sphinx-doc/sphinx

Namespaces packages more than one level deep are not rendered correctly using autodoc

Open
#9,680 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc type:bug
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.