Implicit namespace packages do not generate documentation #298
Comments
|
Oh! Also this is on autoapi 1.6.0, which is the latest available on conda-forge. Sorry if this has been fixed since then! Would be great to get that updated. |
|
We are facing the same issue, any plans to fix this? |
|
Same here, facing same issue: |
We used this custom template as a workaround and it has worked well for us. Check API reference at https://astronomer-providers.rtfd.io/ |
|
Still facing the same issue, as of autoapi version 2.1.1. |
|
For those who land here from a search engine: there's a |
## Description Followed many twists and turns, but have documentation being generated and published to https://michael-christen.github.io/toolbox/ ! Changes were largely based around getting an initial doc tree setup, configuring various plugins, and getting published. - Configuring doc generation to work with bazel by exporting ALL python_sources as a secondary set of files via `filegroup`s. I'm not a huge fan of this / prevents usage of the existing `py_*` targets and in general the cache gets invalidated fairly easily. - Pulled a random icon of a wrench from https://www.flaticon.com/free-icon/wrench_4449037 - Vendored the autoapi templates for control over generated documentation - Working around a summary issue by modifying the autoapi templates: - https://bylr.info/articles/2022/05/10/api-doc-with-sphinx-autoapi/ - readthedocs/sphinx-autoapi#298 - add `publish-docs` workflow to publish docs when committing to master - fixed a `.gitignore` of the `build/` directory - added a bunch of sphinx dependencies - vendored in https://github.com/agoessling/rules_sphinx/tree/3280f704d048dd85400334f7513d0ce11bcdc5f3 to build doc html with bazel We're using a few tools: - https://github.com/peaceiris/actions-gh-pages for publishing to github pages - readthedocs is a nice alternative that could get us mutliple version support: https://app.readthedocs.org/projects/mchristen-toolbox & https://docs.readthedocs.io/en/stable/builds.html (though I wasn't able to get the bazel build working, I think I need to install go as a system dependency, then bazelisk with that, tbd) - https://myst-parser.readthedocs.io/en/latest/ is a pretty neat extension to sphinx that allows you to write most of your documentation in markdown, I've added a few examples for now - for documenting python docstrings we've got: https://github.com/readthedocs/sphinx-autoapi which is a definite improvement over https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html, though looking into https://github.com/sphinx-extensions2/sphinx-autodoc2#design-and-comparison-to-sphinx-autoapi could be interesting Followups: - [Integrate with C++ autodocs (doxygen) and rust / rustdoc](#115) - [Consider only running with bazel, not building as well](#116) - We seem to lose all references to generated code; not sure if that's ok or not, but it does prevent us from treating warnings as errors #117 - #118 - #119 - #120 - #121 - #122 ## Instructions - To add new python files - ensure `python_sources` created in the BUILD file and included in `//docs:docs` sources - if new directory, add to `autoapi_dirs` in `docs/conf.py` - To add new sphinx extensions, modify `docs/conf.py`, add to dep of `//tools/sphinx:sphinx_build_wrapper` ## Test Plan ``` bazel build //docs:docs xdg-open bazel-bin/docs/docs_html/index.html ``` To build and open the docs locally.
|
Is this issue still being looked at? I too have this problem... |
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_namespacesoption is fantastic, but it doesn't create a page for implicit namespace packages. If I have a Python project with the following file layout:autoapiwithautoapi_python_use_implicit_namespaces=Truegenerates the following documentation:In other words, only modules and packages defined with
__init__.pyfiles (explicit packages) are documented with anindex.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:
Thanks!
The text was updated successfully, but these errors were encountered: