gleam-lang
WIP: Links in type signatures
I feel like this has already gotten quite big, so I thought I'd stop at the early point before you say it's all unreasonable anyways and I waste a bunch of time :D
First: I cannot "just" generate links, since highlight.js will not allow them..
Instead, all code relevant to type/function/constant signatures is highlighted at compile time, and types are always printed using the type_::pretty::Printer in the docs. It introduces a new variant to the Document, and a new DocumentWriter trait that can react on them. Since it looked like the documents formatter goes to great length to avoid being recursive, I've also tried to do that. This introduces another new Cmd type that gets used instead of the list of (indent, mode, doc) triples, and consequently changes a lot of types around in format. Just doing recursion would basically get rid of all of that.
Overall, this allows for all signatures (with small extensions all parseable Gleam code) to be highlighted by the compiler directly, without relying on Javascript. This could potentially also be used to add colors/links to error messages, or annotate all examples in the docs as well.
If a resolved type (ignoring aliases) is publicly exposed, a link to its documentation will be generated as well. Versions are currently ignored. Ignoring aliases means that a common pattern doesn't work currently (lustre for example does this with every type), where an internal type is re-exported using a type alias.
Questions
- What about tests? There are existing tests for the docs output which I updated, but generally, I'm a bit lost what you would expect.
- What to do about the alias thing?
fix #3461 #828
Thank you so much for taking a look at this! I kind of put this on hold, since I wanted to wait what your thoughts in the discussion thread were first :slightly_smiling_face:
I had a version with a ZeroWidthString constructor at first but decided against it, since it would have added very HTML/doc-specific things to the formatter. I also unfortunately didn't see the comment, sorry. I ended up with those annotations since they were kind of general (following the highlight.js classes) and allowed me to experiment with syntax highlighting in the CLI output :smile:
A special formatter for printing docs and a ZeroWithString would also solve this, and be indeed a much smaller change to the the pretty module, I'll do that then instead!
I understand why the loop is done this way; I just felt like for sure noone is gonna stack-overflow with the depth of the tree :smile:
