readthedocs / readthedocs/sphinx-autoapi

Implicit namespace packages do not generate documentation

Open
#298 8 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Language: Python
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

  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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.