sphinx-doc / sphinx-doc/sphinx

Autosummary should respect `:meta public:` and `:meta private:`

Open
#8,700 1 comment 7 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.

Currently autodoc allows inserting :meta private: as a way to declare a function private: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

However, autosummary does not do so.

Describe the solution you'd like

In autosummary, functions currently:

List containing names of “public” functions in the module. Here, “public” here means that the name does not start with an underscore. Only available for modules.

If the bold part can be changed to does not start with an underscore and does not have :meta: private, the issue should be resolved.

Describe alternatives you've considered

Customize the autosummary template to exclude each single function that I would like to exclude. Quite tedious though.

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 by tracing how autosummary builds the module functions list and how autodoc processes :meta public: and :meta private:. Update the public-function selection so metadata is respected, then add or run focused autosummary and autodoc tests covering both metadata forms and verify the generated listing.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.