sphinx-doc / sphinx-doc/sphinx
[autosummary] Emit event when generating for a file
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
See tardyp/sphinx-jinja#17 for a use case and detailed description
Is your feature request related to a problem? Please describe.
Other extensions that create code don’t play well with autosummary. An event like this could help
Describe the solution you'd like
An event like
autosummary-file-found(app: Sphinx, file_path: pathlib.Path, lines: list[str])
Where handlers can modify the lines before generate.find_autosummary_in_lines is called on them
Describe alternatives you've considered
One could just manually generate the rst files in conf.py before letting sphinx run, But that lacks flexibility and elegance.
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 at autosummary's generate.find_autosummary_in_lines entry point and trace where each file's lines are prepared. Add the requested autosummary-file-found event before that call, allowing handlers to modify the file path and lines, then verify the behavior with the relevant autosummary tests.
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
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100