No way to override "alias of" text, generated by autodoc

[skirpichev]

Autodoc has problems with resolving references in such text, if the referenced class belongs to the different module, see #2437.

Before #4176 it was possible to workaround this with the currentmodule directive, e.g. here, where this was done to resolve reference to ANP class from polyclasses. Unfortunately, this was broken in latest two releases.

Another option to workaround #2437 would be using comments to document problematic attribute, e.g.:

#: docstring with proper references goes here.
some_attr = SomeClass

Unfortunately, this doesn't work: text "alias of SomeClass" - added after hand-made docstring.

[tk0miya]

+1; it's enough reasonable!

[skirpichev]

@tk0miya, not sure if this is still relevant now, after #2437 is fixed.

Ability to override autogenerated text is important only if it's broken, but that shouldn't be the case anymore.

[tk0miya]

I don't think this is workaround for #2437. This is enough useful for documentation.

[tk0miya]

I check this issue again now. And finally I feel this is not needed. #2437 works well to me.
So I'm closing this now.

[LourensVeen]

I would like to request reopening this issue.

I have a type alias like this:

CopyCallback = Callable[[int, int], None]

which describes the type of a callback function that a user can pass to my copy function. Autodoc currently documents this as:

cerulean.CopyCallback
    alias of typing.Callable

This is not very helpful, first because the arguments to the Callable generic are missing, and second because it doesn't explain what the arguments mean. So I'd like to add a docstring below the definition (and I have), but Autodoc ignores it.

I've added an explanation to the copy function documentation instead, but it would be really nice if the alias could also be documented.

[tk0miya]

Good point! I agree it is useful.
Reopened.

[pauleikis]

Another situation I run into where I had to do code changes to force sphinx generate the docstring.
When implementing strategy pattern.

class StrategyA:
    def algorithm(self):
        pass

class StrategyB:
    def algorithm(self):
        pass

class Context:
    strategy = StrategyA
    """
    there is no way to make this docstring appear. It just says 'alias to StrategyA' 
    even though it is  meant to be configurable and only a default here
    """

    def do_something(self):
        self.strategy(self).algorithm()

I did not find a reasonable way to workaround this except doing a code change and setting the default in the __init__ which is not exactly the same.

[jackalcooper]

Is there any progress on this issue?

[tk0miya]

I just post #7749 to support GenericAlias like CopyCallback.

On the other hand, about @pauleikis's case, latest Sphinx works fine for the example pasted here. So I need to more information to reproduce the trouble. Please file an issue if you still have a problem.

[tk0miya]

Now I fixed the behvior for GenericAlias.
Example:

CopyCallback = Callable[[int, int], None]

And I don't change other behaviors. Please file an issue if you still have a problem around "alias of" text.

[Abrosimov-a-a]

Issue reopen request.

An example of unexpected behavior:

from typing import Union, Type


class MyClass:
    """Class ``MyClass`` docstring."""

    #: This comment is not displayed.
    int_attr = int
    #: This comment is not displayed.
    typed_attr: Union[Type[int], Type[str]] = int

• Sphinx v3.2.1, v3.5.4
• Python v3.7

[tk0miya]

@Abrosimov-a-a Could you file a new issue, please?

[Abrosimov-a-a]

@tk0miya Created #9218