sphinx-doc / sphinx-doc/sphinx
Autosummary should respect `:meta public:` and `:meta private:`
Nobody has claimed this yet.
- 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
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
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