Skip to content

Add a way to avoid repetition for stdlib refs #5

@ItsDrike

Description

@ItsDrike

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions