search

readthedocs / sphinx-autoapi

A new approach to API documentation in Sphinx.
https://sphinx-autoapi.readthedocs.io/
MIT License
415 stars 126 forks source link

`__init__.pyi` treated as module #405

Closed laggykiller closed 4 months ago

laggykiller commented 9 months ago

docs/conf.py

...
autoapi_dirs = [os.path.abspath('../src')]
...

src/__init__.py

'''sample-python-package'''
__version__ = '1.0.0'

src/submodule_foo/__init__.pyi

class Foo:
    def bar(self, a = int) -> None:
        """
        Sample function
        """
        ...

The generated documentation list submodule_foo/__init__ as a module __init__, but it is expected that submodule_foo should be listed as a module.

Note that adding autoapi_file_patterns = ["*.pyi", "*.py"] does not solve the problem.

The expected behaviour is shown if we rename src/submodule_foo/__init__.pyi to src/submodule_foo/__init__.py (Change extension from pyi to py)

Alternative workaround is to change docs/conf.py

autoapi_dirs = [
    os.path.abspath('../src'),
    os.path.abspath('../src/submodule_foo')
    ]
autoapi_python_use_implicit_namespaces = True

The generated documentation would be correct without changing extension from pyi to py

Related issue: https://github.com/readthedocs/sphinx-autoapi/issues/243

Real life example using my project: https://github.com/laggykiller/apngasm-python/tree/stub-to-sphinx

To build the documentation:

git clone --recursive https://github.com/laggykiller/apngasm-python.git
cd ./apngasm-python
git checkout b7ef4f3ce1296461e5f89e4b205a56efaeb7d086
cd ./docs
python install -r ./requirements.txt
make html

This would generate incorrect documentation with __init__ listed as module.

Workaround to build the correct documentation, we have to do this before building documentation:

# Working directory: apngasm-python
mv ./src-python/apngasm_python/_apngasm_python/__init__.pyi ./src-python/apngasm_python/_apngasm_python/__init__.py

This would generate correct documentation with _apngasm_python listed as module.

Alternatively, change docs/conf.py:

autoapi_dirs = [
    os.path.abspath('../src-python/apngasm_python'),
    os.path.abspath('../src-python/apngasm_python/_apngasm_python')
    ]
autoapi_python_use_implicit_namespaces = True

This would also generate correct documentation with _apngasm_python listed as module, without renaming __init__.pyi to __init__.py.

I propose this PR to solve this problem: https://github.com/readthedocs/sphinx-autoapi/pull/406

You may test that the PR works by:

git clone --recursive https://github.com/laggykiller/apngasm-python.git
cd ./apngasm-python
git checkout dd3b3da89640a641683163da81a72ec4eed0f376
cd ./docs
python install -r ./requirements.txt
make html

The commit uses my own fork with the patch, and the correct documentation is generated.