You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
The text was updated successfully, but these errors were encountered:
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 withalias 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:
Which would produce a table where the summary text would be the first line of the docstrings for both
obj1
andobj2
, regardless of whetherobj1.__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.
The text was updated successfully, but these errors were encountered: