Description
Pre-PEP8 aliases are currently defined as references to the new objects, which means autodoc sees two names with the same docstring and generates two copies of the documentation for each one. This duplicate information accounts for over 15% (!) of the page space in the pyparsing API reference.
I decided to file an issue before making a PR to find out what the devs' preference would be (plus, I don't know how long the deprecated aliases are meant to stay around). The documentation for an alias could be:
- a copy of the full documentation (as it is now)
- a deprecation note with a link to the updated name
- a deprecation note and link, followed by a copy of the full documentation
- hidden altogether
I have a pretty good idea how each option could be implemented without copy-pasting documentation, so I'm curious which would be preferred. (We might even be able to hook autodoc-process-docstring to trim the Sphinx output down while keeping the full documentation in __doc__ for the REPL.)