-
Notifications
You must be signed in to change notification settings - Fork 0
Description
While the library already provides a nice way to avoid repetition with relative cross-references, such as:
"""
[`MyClass`][..]
"""This approach only works because the reference gets converted into ..MyClass. This however doesn't work very well for builtins. Since builtins shouldn't have any path prefix, we need a different approach for this.
A potential solution might be to introduce a symbol for builtins refs, for example $, which would allow us to do something like:
"""
[`TimeoutError`][$]
"""
# instead of
'""
[`TimeoutError`][TimeoutError]
"""Question is whether there's some benefit in still enforcing consistency and doing [$.], with the dot expanding into the builtin, or whether to just special case $ to work without this too. An important question to address before making this decision is: Is there some benefit to referencing parameters of builtins?
Note that this might be beneficial for more than just builtins, right now, any refs that are written out in full (e.g. [asyncio.Transport] need to use a full reference path too, since doing [asyncio.] doesn't make sense (would become asyncio.asyncio.Transport). Allowing the use of $ for this purpose too might be quite nice for repetition avoiding even in here.