Remove redundant documentation about aliased functions from HTML docs

[vincentmacri]

Problem Description

Some functions in Sage have two or more names. This is implemented in one of the following two ways:

def foo():
    return 0

def foo():
    return bar()

or

def foo():
    return 0

bar = foo

For the latter, bar will inherit the same docstring as foo. This is good for use in an interactive setting, but redundant in the HTML documentation as it duplicates the method description.

For example, IntegerMod has sqrt and square_root. As you can see in the linked HTML documentation, the entire docstring is repeated for both. This makes the documentation appear more complicated and adds no useful information.

Proposed Solution

For aliased methods/classes/etc, the HTML documentation should only include the full docstring for the original. For the aliases it should instead say something like "Alias for [link to original]". Ideally this does not change behaviour in interactive sessions, only in the HTML documentation (and probably PDF documentation, but that doesn't entirely work right now).

Alternatives Considered

None

Additional Information

There is some code present in the docbuild scripts that seems like it is supposed to do this, but it isn't used.

Is there an existing issue for this?

• I have searched the existing issues for a bug report that matches the one I want to file, without success.

[user202729]

Good idea. Currently we have deprecated_function_alias that makes a wrapper function with modified __doc__, we may also make something like function_alias that also makes a wrapper function and modify the __doc__.

That is likely less flaky/magical than using doc build script (how do you reliably detect which copy of the function is the original and which is the alias?).

Unless you can make the HTML display something like

method sqrt(...):
method square_root(...):
<description>

then there's no problem.

[vincentmacri]

how do you reliably detect which copy of the function is the original and which is the alias?

I've started working on this and so far it seems I can reliably detect which copy of the function is the original and which is the alias. When Sphinx parses the docstring it exposes the function name as it appears in the docs and the Python object corresponding to the function. If those don't match then it's an alias. There are a couple edge cases to this that I am working on special casing (i.e. lambda functions and factories).