sphinx-doc / sphinx-doc/sphinx

Allow custom documenters in autosummary

Open
#6,264 4 comments 5 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'd like to have autosummary be able to recognize autodoc documenters other than the built-in ones. E.g. celery tasks. Celery brings it's own documenter [1] in an extension, but the typ of task is not recognized.

[1] http://docs.celeryproject.org/en/latest/_modules/celery/contrib/sphinx.html#TaskDocumenter

Describe the solution you'd like

The code below could be turned into a loop with configurable inputs:

https://github.com/sphinx-doc/sphinx/blob/d501bc136ce5069e97a5f347dbc694717dddced8/sphinx/ext/autosummary/generate.py#L192-L198

The list could be automatically, or manually, extended with further documenters, via conf.py or from other extensions.

Describe alternatives you've considered

  • configure via conf.py
  • configure from other extension
  • determine directly from registered documenters

(The last would be great - although a question is how to know what is available when adapting the jinja template)

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 sphinx/ext/autosummary/generate.py around lines 192-198, where the built-in documenter types are handled. Read how autodoc documenters are registered and how conf.py or extensions could provide them, then check the Jinja template inputs. Done means autosummary recognizes registered custom documenters such as Celery's task documenter without breaking existing built-ins.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 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.