intra doc links instead of relative file paths

[ben0x539]

Motivation

#940, I guess. I kept running into the odd broken link in the docs and eventually realized it's because a lot of stuff is reexported in parent modules and so the file path based relative links couldn't possibly work in all contexts. Looks like master already underwent this treatment but I suspect this is easier than backporting.

Solution

Intra-doc links seem pretty good.

I started with

        find -name \*.rs -exec sed -i -e '
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\w\+\.\(\w\+\)\.html@\1super::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\w\+\.\(\w\+\)\.html@\1super::super::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\.\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1super::super::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/index\.html@\1super::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./index\.html@\1super@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\.\./\(\w\+\)/\?$@\1super::\2@;
    
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\w\+\.\(\w\+\)\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/index\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./index\.html@\1self@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\./\(\w\+\)/\?$@\1self::\2@;
    
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\w\+\.\(\w\+\)\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\w\+\.\(\w\+\)\.html@\1self::\2::\3@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/index\.html@\1self::\2@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?index\.html@\1self@;
            s@\(//. \[[^]]*\]:\s\+\)[:"]\?\(\w\+\)/\?$@\1self::\2@;
    
            s@\(//. \[[^]]*\]:\s\+[A-Za-z_0-9:]\+\)#method\.\(\w\+\)@\1::\2@;
        ' {} +

and then removed redundant self::s when I realized you don't actually need a :: in the links, and fixed stuff up by hand as I ran into errors from

x='--cfg docsrs --cfg tracing_unstable'; RUSTFLAGS=$x RUSTDOCFLAGS=$x cargo doc --all-features

I hope that's roughly how the docs are supposed to work.

I understand this is a relatively big unsolicited change in that it touches a whole lot of files (definitely went further than I originally intended), I'm happy to revise or split or reduce scope of this PR as desired.

[ben0x539]

idk what to do about html links though, there's a bunch of stuff inside weird tags where markdown doesn't apply

[hawkw]

At a glance, this looks good to me --- thanks for working on this. I believe the Netlify docs preview CI job would fail if any of the new links were broken, so I don't think we actually need to manually check them.

Regarding

idk what to do about html links though, there's a bunch of stuff inside weird tags where markdown doesn't apply

I don't think we can do anything about those here; the explicit HTML links are used because RustDoc appears to not parse markdown inside of HTML tags. So, I don't think those can easily be made intra-doc links.

[hawkw]

can we also apply this treatment to docs links to the standard library? it would be fine to do that in a separate PR, though.

[ben0x539]

definitely (tho prefer separate pr), i'm gonna read up more on how those links work for cross crate references :v

[ben0x539]

👍 yeah cargo doc complains about broken links and i pretty much iterated until it stopped

[hawkw]

Cool, this is probably good to merge as-is, then! Thanks again!