While the library already provides a nice way to avoid repetition with relative cross-references, such as:
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.
While the library already provides a nice way to avoid repetition with relative cross-references, such as:
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: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 becomeasyncio.asyncio.Transport). Allowing the use of$for this purpose too might be quite nice for repetition avoiding even in here.