search

mersinvald / aquamarine

Inline diagrams for rustdoc with mermaid.js
MIT License
487 stars 25 forks source link

Symbol hyperlinks #18

Open temportalflux opened 2 years ago

temportalflux commented 2 years ago

Mermaid has support for interactions on flow-chart nodes and rustdocs can generate links to items by name. I'd be very helpful to be able to use both of these concepts and allow crate users to add links to nodes in mermaid syntax utilizing rustdocs item linkage syntax. Something like:

graph TD
  Item1["[Shown Text](rustdocs::symbol::path)"]

which would show something like

graph TD
    Item1[Shown Text]

but where Shown Text is also a hyperlink to wherever the rustdocs hyperlink for rustdocs::symbol::path leads.

This WOULD require specifying securityLevel:'loose' in the mermaid config.

mersinvald commented 2 years ago

@temportalflux do you think it would be sufficient to set securityLevel: loose as a default, under a hyperlinks feature gate?

I don't want to make it a universal default, partly because it's a breaking change, and also because it is a security issue that I'm not qualified to assess, to be completely honest.

temportalflux commented 2 years ago

Yeah I think exposing that option would be fine, though I suspect it would only get integration halfway there. Since mermaid seems to want full url links, there would need to be some mechanism, enabled by a hyperlinks flag, that converts rustdoc links in a mermaid block into true urls. Perhaps a preprocessor that asks rustdoc to return a hyper link given some rustdoc sybtax that aquamarine detects inside a mermaid-code-block.

mersinvald commented 2 years ago

I'll see if I can find some heuristic to do that, but it it's something that requires getting information from rustdoc, then we're pretty much out of luck

temportalflux commented 2 years ago

It looks like resolving hyperlinks via rustdoc might be viable? I just happened upon this tutorial today which seems to do something similar via some unstable/nightly functionality in rustdoc. https://scrabsha.github.io/abcr-issue-0/#the-basic-idea https://doc.rust-lang.org/rustdoc/unstable-features.html#-w--output-format-output-format

frehberg commented 1 year ago

Maybe this code snippet might be used to implement some kind of intelligent callback function to redirect to the API doc https://stackoverflow.com/a/73733645