Rust Docs: Relative links and linking to other structs


#1

Hi,
So I really want my docs to be as pretty as the ones on the website, but unfortunately I did not find out how to generate docs with relative links. E.g. I have an implementation of PartialOrd and Ord and the Ord panics if PartialOrd returns None (the reason being that I’m waiting for a feature which is on the list of future rust features. after which this will be corrected).

Nevertheless in the docs I want to write something of the sort:
Ord derives directly from [link to PartialOrd implmentation], but do it without a hard link.

I just need a small example that’s all.


#2

You have to write it all manually.


#3

Okay thanks for the answer. I guess it might be worth in some distant future to add this as possible feature, similar to the javadoc syntax.


#4

Yup! It’s just an inherent problem with Markdown, it doesn’t come with any support for this kind of thing.


#5

which is why I never understood the Markdown hype. But hey, Github uses it, it must be great!


#6

which is why I never understood the Markdown hype. But hey, Github uses it, it must be great!

Ease of use is a big part of its appeal. I’ve used ReStructured Text extensively, and it can handle this kind of thing automatically, but is non-trivially more difficult to write correctly. As usual, these kinds of decisions are a tradeoff—and in my opinion the last thing in the world you want to do is make documentation harder to write. :wink: