Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify the 4 types of links and RefInfo. #383

Open
Carreau opened this issue Jan 22, 2024 · 0 comments
Open

Clarify the 4 types of links and RefInfo. #383

Carreau opened this issue Jan 22, 2024 · 0 comments

Comments

@Carreau
Copy link
Member

Carreau commented Jan 22, 2024

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.

@Carreau Carreau changed the title Calrify the 4 types of links and RefInfo. Clarify the 4 types of links and RefInfo. Jan 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant