sphinx-doc / sphinx-doc/sphinx
Broken autosummary links when using "empty" automodule directive
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
When auto-documenting a Python source, autosummary table links are not rendered/recognized when an automodule directive of the same module with no member declarations precedes them.
Description
- When a
autosummarydirective is preceded by aautomoduledirective with no member declarations (to just include the docstring of that module), theautosummarytable in the HTML output will not link to any manually (auto) documented members in that module, that are documented after theautosummarydirective. - Sphinx renders the project without any errors or warnings.
- I have only tested this for HTML output.
- At least in my case this is only happening in sub modules, but not in the package module.
- Removing these
automodulestatements to just include the module docstrings will "fix" the problem.
Example
Here is a minified example, I also added some C-style comments to mark some parts, because rst-comments are so unreadable.
some_package.a_module
=====================
.. toctree::
:hidden:
some_class_page
.. automodule:: some_package.a_module // 1
.. note::
A note that contains a reference to the module itself :mod:`some_package.a_module`.
.. rubric:: Classes
.. autosummary::
:nosignatures:
some_package.a_module.SomeClass //4
.. rubric:: Functions
.. autosummary::
:nosignatures:
some_package.a_module.some_function // 2
Functions
---------
.. autofunction:: some_package.a_module.some_function // 3
- Removing
1will fix the broken links. - With
1not removed, the table entry created by2will not link to3. - Also
4will not link to the class definition in the pagesome_class_page.
Environment info
- OS: Win
- Python version: 3.7
- Sphinx version: 2.4.3
- Sphinx extensions:
extensions = [ "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.autosectionlabel", "sphinx.ext.inheritance_diagram", ]
Cheers,
Ferdinand
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the minimal example with automodule, autosummary, and autofunction in an HTML Sphinx build, then compare the output with the empty automodule removed. Trace how these directives resolve module and member references; done means the autosummary entries link to the manually documented function and class without warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100