Documentation links are difficult

[matthew-piziak]

Workflow criteria

An efficient workflow must satisfy one of two criteria:

• Determinism: the change of success per attempt is high.
• Iteration Speed: the frequency of attempts is high.

Composing links in documentation does not currently satisfy either of these criteria. The rules for linking are mysterious enough that a contributor cannot be confident that they will work without running make docs.

Examples of pain

#32130: a struct can be viewed from two locations, at varying depths of links; sometimes links to methods refer to the wrong modules.
#35880: doc entities are replicated between std and core.
#35759: directory links are confusing; anchors are case sensitive and do not match rendered content.
#rust-docs logs: Linkchecker is not always reliable (or potentially has usability problems).
#rust-docs logs: If a URL is present in both item description and short description, in the second case it won't work.

Potential resolutions

My hope is that this problem is procedural. It's entirely likely that I'm just wrong! If that's the case, then this issue can be resolved with documentation that either: 1) specifies a fast way to programmatically check docs locally, or 2) specifies a deterministic set of rules (a checklist) that allows a contributor to verify that their links will be successful without compiling them.

If I'm not wrong, then the problem becomes more difficult, which is why I created this issue. I appreciate any insight from more experienced members of the community.

[ollie27]

#rust-docs logs: Linkchecker is not always reliable (or potentially has usability problems).

There seems to have been some confusion here. linkchecker needs to be run on the doc output directory, not the source code directory. So assuming you're using the Makefiles the full instructions would look something like:

$ ./configure
$ make docs
$ cd src/tools/linkchecker
$ cargo run --release -- ../../../doc

[durka]

3. Make up a real syntax for linking to Rust items (requires a Markdown extension or pre/postprocessor). See RFC: Relative link syntax for rustdoc rfcs#1661 (postponed)

[steveklabnik]

rust-lang/rfcs#1946 should help with this!

[steveklabnik]

RFC was merged, closing as a duplicate of #43466