sphinx-autoapi
sphinx-autoapi copied to clipboard
`autoapimodule` directive in "manual mode": Imported members are documented
Above: Imports visible in documentation with .. autoapimodule
directive
Related: #262, #317
Reproduction
https://github.com/vcs-python/libvcs/tree/autoapi-duplicates
Versions
sphinx 5.1.0 sphinx-autoapi 1.9.0
Configuration
extensions = [
"sphinx.ext.napoleon",
"autoapi.extension",
"sphinx.ext.autodoc",
"sphinx.ext.todo",
"sphinx.ext.intersphinx",
"myst_parser",
]
# sphinx-autoapi
autoapi_type = "python"
autoapi_dirs = [project_root / "libvcs"]
autoapi_generate_api_docs = False # when False, use directives
Directions
-
git clone https://github.com/vcs-python/libvcs.git --branch autoapi-duplicates
-
cd libvcs
-
poetry install
-
make start_docs
- http://localhost:127.0.0.1
- Examples:
-
projects.git
localhost: http://localhost:8064/projects/git.html markdown source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/docs/projects/git.md python source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/libvcs/projects/git.py -
cmd.git
localhost: http://localhost:8064/cmd/git.html markdown source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/docs/cmd/git.md python source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/libvcs/cmd/git.py -
_internal.run
localhost: http://localhost:8064/internals/run.html, e.g.StrOrBytesPath
markdown source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/docs/internals/run.md python source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/libvcs/_internal/run.py
-
- Workarounds to scope:
-
__all__
does not work:projects.hg
localhost: http://localhost:8064/projects/hg.html markdown source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/docs/projects/hg.md python source: https://github.com/vcs-python/libvcs/blob/autoapi-duplicates/libvcs/projects/hg.py
-
Workaround
Workaround ATM exclude-members
for each usage:
.. autoapimodule:: libvcs.projects.git
:members:
:show-inheritance:
:undoc-members:
:exclude-members: BaseProject, StrOrBytesPath, StrPath
Discussion
- Any better workarounds?
- Is this a bug or expected behavior?
- Could my package structure be playing a role?
- Anyone else experiencing this? Ideas / workarounds?
Updated example from sphinx 5.0 to 5.1, autoapi 1.8.0 -> 1.9.0
Not sure if this is the same issue, related or something else entirely, but the autoapi-skip-member
event also doesn't seem to fire for things documented by autoapimodule
directives.