sphinx-doc / sphinx-doc/sphinx

Broken autosummary links when using "empty" automodule directive

Open
#7,500 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
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 autosummary directive is preceded by a automodule directive with no member declarations (to just include the docstring of that module), theautosummary table in the HTML output will not link to any manually (auto) documented members in that module, that are documented after the autosummary directive.
  • 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 automodule statements 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 1 will fix the broken links.
  • With 1 not removed, the table entry created by 2 will not link to 3.
  • Also 4 will not link to the class definition in the page some_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

Open the contributing guide

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.