sphinx-doc / sphinx-doc/sphinx

Autosummary: option to suppress automatic "alias of" in table summary

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

Autosummary typically uses the first line of the docstring in the table it produces to summarize each item. In cases where __name__ refers to another object, the summary text is instead replaced with alias of {obj.__name__}. There are cases where the selection logic based on __name__ is a poor fit for determining aliases (see context).

Describe the solution you'd like
A way to suppress the automatic "alias of" insertion. For instance:

.. autosummary::
   :toctree: generated/
   :no-aliases:

   obj1
   obj2

Which would produce a table where the summary text would be the first line of the docstrings for both obj1 and obj2, regardless of whether obj1.__name__ == obj2.__name__.

Describe alternatives you've considered
Skipping autosummary entirely and using individual autodoc directives for each object to guarantee the links are generated, then organizing the results into tables manually.
Alternatively, if there is a way to autogenerate .rst files for objects (i.e. replicate the behavior of .. autosummary with :toctree:) without including any summary in the text at all. Basically just using autosummary for generating links, but not including any text in the file where autosummary was called.

Additional context
This came up in the context of documenting scalar types in NumPy, the documentation for which is itself autogenerated and platform dependent. See numpy/numpy#16884 for the original attempt and numpy/numpy#17331 for a proposed workaround.

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 at Sphinx's autosummary directive and search for the code that inserts the automatic "alias of" summary. Trace how directive options are parsed and how table summaries are selected. Done means a :no-aliases: option uses each object's first docstring line even when names match, with coverage for both alias and non-alias cases.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.