Allow sidebar links to be specified for Rustdoc

[syvb]

This should implement everything needed in rustc to implement #72475 (although automatically adding links based on Cargo.toml would have to be implemented in cargo-doc). It allows an arbitrary links to be added to be added to the left sidebar. These are only displayed on the crate root.

Sidebar links can be specified in two ways:

• On the commandline, like rustdoc src/lib.rs --sidebar-url Homepage=http://rust-lang.org --sidebar-url "Repository URL"="https://example.com/ a"
• As a #[doc] attribute:

#![doc(
    sidebar_url(
        name = "Repository",
        url = "https://github.com/rust-lang/rust",
    )
)]

Screenshot

Notes

• Invalid #[doc] attributes are, and always have been silently ignored.
• Links are sorted Unicode order.
• Later command-line flags override earlier command-line flags.
• #[doc] attributes override commnad-line flags in the case of a disagreement.
• Later #[doc] attributes override earlier #[doc] attributes.
• Currently it is stable. It could be added as unstable, but since it uses both the #[doc] attribute and command line config, it's unclear if it should be enabled by a seperate rustdoc flag, or by a rust feature (I can't find any info on this).

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @GuillaumeGomez (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[GuillaumeGomez]

First, thanks for opening this PR! Now, a few things to be noted though:

• I'm not really comfortable with the idea of adding links just like this, or at least added in the sidebar. I think a new section on the crate index.html file would better to differentiate between the crates' links and the crates' repositories.
• This should be kept as unstable for the moment (so if this isn't a nightly build, you shouldn't allow this) simply because we can't merge something that might change quickly directly as stable.
• I think this should only be done with command-line option (and through cargo), so the extension of #[doc()] seems to be too much for me.

What do you think @rust-lang/rustdoc ?

[kinnison]

I think that if it were a section for index.html then you could just put the links in the inner doc of lib.rs or main.rs so perhaps sidebar is special in some sense. I think only via commandline args is fine; and thence Cargo.toml via cargo doc perhaps.

I quite like seeing where it shows up in the examples in the screenshots, but I wonder if this will end up conflicting with things docs.rs might want to inject?

[bors]

☔ The latest upstream changes (presumably #73767) made this pull request unmergeable. Please resolve the merge conflicts.

[syvb]

I've fixed the merge conflicts and rebased on to master. I've also renamed the flag to --crate-root-link. The flag is currently used like:

rustdoc +local src/lib.rs -Z unstable-options --crate-root-link Repo=https://a.com --crate-root-link "Web site"="https://a.com"

Here's what it looks like on smaller screens:

[Dylan-DPC-zz]

After a discussion with the reviewer, they don't feel that it is a good idea to merge this at this point in time. If you wish you can find a better way we can tackle this problem. Closing this for now. Thanks for taking the time to contribute.

[GuillaumeGomez]

Still remains the worry about those newly added links: basically, it's very easy to put whatever you want in there. Just imagine some crates adding ads or whatever, that would be pretty bad and I'm not sure we should allow it.

What do you think @rust-lang/docs-rs ?

[jyn514]

The main places documentation shows up are

• docs.rs
• locally

If you document it locally, I don't think we should care about where the link goes, if you want to show yourself ads then fine.
If you document on docs.rs, it will use cargo doc. Since rustdoc don't allow arguments to be specified multiple times, cargo doc will pass --crate-root-link and passing it in RUSTDOCFLAGS as well will be an error. So also there I don't think we need to worry about ads.

Is there any concern you had about it other than ads? Otherwise I think this should be reopened.

[jyn514]

Oh and the third place is on a self-hosted documentation site, but if you've already gone to a random website I think that implies some level of trust (and you can put arbitrary links on your own site anyway).

[jyn514]

Please revert this change. There are systems that do not have python3 installed (#71818 (comment)). If you have trouble locally you can make a symbolic link from python3 to python.

Suggested change

	#!/usr/bin/env python3
	#!/usr/bin/env python

[jyn514]

This should be optflag and not optmulti to make sure passing it in both cargo doc and RUSTFLAGS is an error.