💡 Alternative Design Idea

[zicklag]

So I just had an idea that I might try out, but I figured I'd run by you to see what you think.

What if we just used rustdoc to generate the HTML file for the lib.rs file, and then parsed the HTML to modify the links to point to docs.rs. We might not even have to convert it to markdown because markdown does allow HTML inside it, as long as it doesn't do anything spooky.

Then we are depending on the reliability of rustdoc to actually generate the documentation and the links, knowing things like what's a struct, what's a method, and producing the proper struct.MyStruct.html style links instead of us having to use the search feature to find items.

[msrd0]

and then parsed the HTML to modify the links to point to docs.rs

I was thinking about several solutions on how to get more reliable doc links. Using rustdoc might be one, but afaik rustdoc's output is not stable (I believe someone suggested rustdoc to output stuff in JSON format, but I don't think that's been implemented yet). Another idea I had was to utilize rust-analyzer to resolve all links, since it can probably tell us if the referenced item is a struct, enum, module etc. This is especially problematic for re-exports, as links like https://docs.rs/gotham/0.6.0/gotham/?search=gotham%3A%3Ahyper%3A%3AStatusCode are valid in rust, but not in rustdoc.

We might not even have to convert it to markdown because markdown does allow HTML inside it, as long as it doesn't do anything spooky.

I intially wanted to make the generated markdown file to contain mostly html, given that it's easier to place a closing tag than it is to insert newlines with correct indentation. However, some markdown renderers (I use grip for previewing) did not render markdown if it was not at least two lines away from any html tags in the same file. That's why I decided that it's a bad idea to output HTML by default, as it might mess with templates that use markdown syntax.

[zicklag]

Using rustdoc might be one, but afaik rustdoc's output is not stable (I believe someone suggested rustdoc to output stuff in JSON format, but I don't think that's been implemented yet).

Ah, bummer that's a good point.

Another idea I had was to utilize rust-analyzer to resolve all links, since it can probably tell us if the referenced item is a struct, enum, module etc.

That sounds like a good idea. The IDE get's all of the information we need so it has to be able to provide what we're looking for. I think it's just a simple JSON RPC over stdout/stdin to use the rust-analyzer binary, too.

[msrd0]

Do you want to work on this? I haven't looked into using rust-analyzer at all, it was just an idea I had once.

[zicklag]

I might check it out, but not guarantees yet. I'll look at it and see if it might be simple.

[zicklag]

I just verified that rust-analyzer is indeed a valid language server protocol ( LSP ) server which uses a JSON RPC over stdin and stdout. We should be able to interact with it simply by running the rust-analyzer command off of the system and sending/receiving JSON from it. I haven't tried it yet, but I think that we'd be able to use the workspace/symbol request and use the symbolKind field to get the info we need to construct accurate docs.rs links.