sphinx-doc / sphinx-doc/sphinx

Allow disabling addition of brackets in the signature mangling in autosummary

Open
#10,053 0 comments 0 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

The autosummary extension mangles signatures in the summary table by adding brackets to signatures whenever there are optional arguments. For example, a signature like

def func(x, *, arg1, arg2):

will be mangled to

func(x, *[,arg1, arg2])

This behavior is hard-coded in the autosummary code here. The only way to disable it is to monkeypatch mangle_signature in conf.py, like

import sphinx.ext.autosummary as autosummary_mod
if hasattr(autosummary_mod, '_module'):
    # It's a sphinx deprecated module wrapper object
    autosummary_mod = autosummary_mod._module
autosummary_mod.mangle_signature = lambda sig, max_chars=30: sig

I would prefer for the table to not add the brackets and ellipses to the signatures, as these are not valid Python code, and don't add anything to the original valid-Python signature. Frankly I think this behavior should not be there at all, but there should at least be an option to disable it.

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/init.py at the mangle_signature call around the linked line, then trace how autosummary options are read. Add a configuration option that controls bracket and ellipsis insertion, and verify that disabling it preserves the original valid-Python signature in summary tables.

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
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.