I'de like to work on this issue. This is a major thing that pydoctor does not do yet.

I'm just not sure about skipping undocumented aliases tho ?
I think alias should be always given a documentation entry, even when not documented.

To clarify the difference between aliases and constants, we could do the following:

• create the new alias kind
• create a is_alias(expr) -> bool function and change ModuleVistor._handleAliasing() method such that, instead of hacking the redirection with ctx._localNameToFullName_map[target] = full_name, it creates a legit Attribute documentable and it returns None, like other _handle* methods.
• Move the _handleAliasing() calls at the same places we check for the constants, this will allow to spot alias inside a class context, too.
• first check if the assignment is an alias, then check if it's a constant. This way, the code in your example @mthuurne will be considered aliases and not constants.
  - An alias can could be defined as follow: single assignment that points to a ast.Name or ast.Attribute nodes OR an import and re-export of names that are not part of the current system. I propose to remove the check if target in ctx.contents from _handleAliasing()because this would allow to document things such as the constantly re-export and more generally things that are not from the current scope but we've imported and assigned a alias.
  - The expandName() method should be changed such that it follows the alias when possible.
  - The _importNames() method should be changed such that it creates an alias when a re-exported name is not part of the current system, instead of ignoring it.
• The alias could have an autogenerated text showing "Alias to <object name that we tried to link/colorize with the PyvalColorizer>" (see Constant values and decorators colorizing #402)

I'm working on this issue and I have a somewhat generic question:

import sys
Class A:
    if sys.version_info[0] < 3:
        alias = B.a
    else:
        alias = B.b
Class B:
    a = 3
    b = 4

try:
    import .ssl as _ssl
except ImportError:
    alias = None
else:
    alias = _ssl

Should the alias attribute be documented? Or should we ignore (still keeping track of the indirection) it in both cases because the assignment is not on the root level of it's context ?

Meaning that, changing the declaration as follows would mean that it would be documented.

import sys
Class A:
    alias = None
    if sys.version_info[0] < 3:
        alias = B.a
    else:
        alias = B.b
Class B:
    a = 3
    b = 4

alias = None
try:
    import .ssl as _ssl
except ImportError:
    alias = None
else:
    alias = _ssl

Thanks for answers!

PS : I'm asking because there are lots of these cases (especially for modules - but I assume it should work the same for classes) in Twisted and it looks like it's mostly used for sorting out imports that might raise an ImportError. Aliases were originally not created a Documentable entry in the _handleAliasing function, so this was not creating a lot of noise in the documentation , now that we do, it's creating lots of entries that are not really worth it documenting. But at the same time they might be example where we would like to document stuff inside an if block...

Now that I'm thinking about it, I think we should probably create an alias entry even if the aliases are not defined at the root level of the context.

But only show them if they are documented.