sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.6k stars 2.12k forks source link

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

Open michiel007 opened 3 years ago

michiel007 commented 3 years ago

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

TheVinhLuong102 commented 5 months ago

Thank you @michiel007 for reporting. I am having the same issue now.

Hi @AA-Turner, is there a plan for this one being fixed soon? Thank you.