Autosummary lists functions but does not generate documentation pages

[aeisenbarth]

Describe the bug

When using autosummary with recursion, functions in the summaries are not clickable while modules are. There is no page with full documentation generated for each function.

I see that other projects have full documentation of their functions, and I assume this is the wanted behavior. I also don't see other projects having extra stub generating scripts besides autosummary_generate = True.

Actual behavior

Function is not clickable

Expected behavior

Function is clickable

How to Reproduce

my_module.py

def my_function(*args, **kwargs):
    pass

conf.py

extensions = ["sphinx.ext.autosummary"]
autosummary_generate = True

index.rst

.. autosummary::
   :toctree:
   :recursive:

   my_module

Environment Information

Platform:              linux; (Linux-5.15.0-91-generic-x86_64-with-glibc2.35)
Python version:        3.9.17 (main, Jul  5 2023, 20:41:20) 
[GCC 11.2.0])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

["sphinx.ext.autosummary"]

Additional context

No response

[aeisenbarth]

A workaround is to copy the original template to _templates/autosummary/module.rst in your root docs directory and patch a single line in the functions section:

--- module.rst
+++ module.rst
@@ -18,6 +18,7 @@
    .. rubric:: {{ _('Functions') }}
 
    .. autosummary::
+      :toctree:
    {% for item in functions %}
       {{ item }}

As a downside, the custom template copies a lot of unchanged code, which does not get updates if you update sphinx.

---

Should I create a pull request? Is this the right place to fix, and are there other items like classes/methods where this also need to be applied?

[jayaddison]

I see that other projects have full documentation of their functions, and I assume this is the wanted behavior. I also don't see other projects having extra stub generating scripts besides autosummary_generate = True.

@aeisenbarth could you link to a sample documentation project that does offer hyperlinked function documentation? (preferably one with an open source license, to make it easier to compare the configuration details)

[aeisenbarth]

• Scanpy docs
• SpatialData docs

After further inspection, I am not sure whether there is some extra build process on top of what is specified in conf.py, when projects are hosted on readthedocs? (maybe sphinx-autoapi)

Others (xarray) explicitly specify every item.

I didn't observe projects that use autosummary to summarize unclickable items, but not document the items in some way. It seems to be desirable to document them. The question is maybe whether autosummary should do it by default or rather not.