Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rossbar opened this issue Oct 2, 2020 · 1 comment
Open
Labels
extensions:autosummary type:enhancement enhance or introduce a new feature

Comments

@rossbar
Copy link

rossbar commented Oct 2, 2020

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.

@rossbar rossbar added the type:enhancement enhance or introduce a new feature label Oct 2, 2020
@eric-wieser
Copy link
Contributor

@rossbar, just to be clear - in the numpy case not only does obj1.__name__ == obj2.__name__, but obj1 is obj2.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
extensions:autosummary type:enhancement enhance or introduce a new feature
Projects
None yet
Development

No branches or pull requests

3 participants