Skip to content

Clarify the 4 types of links and RefInfo. #383

Open
@Carreau

Description

@Carreau

From my experience, there are 4 types of "Links" we can encounter.

  • Links from with a document that refer to another thing in the document.
    For example in a docstring that refer to a parameter of the signature. This is typically rendered as an html-anchor in most document, or just render differently, like bold.
    Those use RefInfo with "local" I think in one of the fields. This is weird-ish in the codebase as you don't really need to resolve them

  • Links from within the same library, same version. Those make more send, except the module and version fields don't make much sens. This is typically for a See-Also, or any other reference.

Those two can get resolved during/just after Gen, but don't need to be resolved at crosslink.

  • Links to an object/page in another library. This is currently what Links/RefInfo are designed for.

  • External link to URLs, or any other resources. Those don't need resolution ever. We could have some magic stuff for some things like wikipedia, or GitHub but not critical.

Maybe we should think about having different types for each.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions