grain-lang
Hyperlinks in graindoc
There are a lot of details to work out, but it would be great if graindoc had some capacity to auto-generate hyperlinks to functions in documentation. For example:
Uses the generic `==` equality operator.
It'd be great if we could have some special syntax which would result in == linking to Pervasives.(==).
I'm not 100% sure this makes sense to implement. The use case for it would be making documentation more navigatiable but I feel like the issues aren't something we can easily overcome, especially as graindoc is used outside of the stdlib by users.
-
==is in the stdlib what happens when a user does this from their project? (The docs won't be hosted on their server) - When building the hyperlinks we would have to assume how the documentation is hosted on their server.
- Given graindoc allows raw markdown, this would conflcit with inline embed syntax possibly causing issues.
It seems a lot easier and a lot more customizable to make use of markdown links instead, we could make more an effort to use them in our documentation if we feel it's needed, combined with algolia search on the new website I think a lot of these issues would be solved.
Single document links would avoid some of these issues but I think the use case is too narrow to consider implementing it over the markdown syntax.
Given the issues with implementing this and the alternative i'm just not sure it makes sense.
