sphinx-doc / sphinx-doc/sphinx

autosummary generator and templates should support module data (ie fields/constants)

Open
#6,794 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.
I want to use the autosummary_generate to automatically generate rst files for a large project. Some of my modules define data constants. I'm using a customized module.rst template to get the output just the way I want, but there is no way to include the module data in the output.

Describe the solution you'd like
autosummary_generate should support module data just as it currently support module classes/exceptions/functions, i.e. by providing a "data" variable containing a list of the data items defined in this module, which could be used with autodata or similar. This would need to be added in the generate_autosummary_content function of generate.py

Maybe the default autosummary module.rst template should display data fields (just like automodule does), but that's less pressing - the most important thing is to add it to the templating so that at least people can add it themselves if needed.

Describe alternatives you've considered
I tried using "members" as a workaround (since I figured any member that's not in functions/classes/exceptions must be data) however annoyingly/surprisingly members is implemented using dir(module) rather than the get_members() function all the others use, so bypasses the normal logic for deciding about private/non-private and direct members vs imported so includes far too much junk to be useful.
https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html

I can't see any extension hooks that would enable an enduser of sphinx to add this capability without forking/changing the autosummary extension itself

Additional context
(While we're at it, a list of submodules would be really nice too)

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

Start in generate.py at generate_autosummary_content, then compare how the existing classes, exceptions, and functions data are collected and exposed to templates. Add the module data list so a customized module.rst template can consume it while preserving the existing member filtering behavior. Verify the generated template context includes the expected data items.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.