Justification of html_root_url is missing nuance

[jyn514]

cc #75, @dtolnay

From rust-cli/env_logger#185:

The scenario where this goes wrong (assuming you're the author of env_logger and not using html_root_url) is:

1. Another downstream crate uses env_logger as a dependency
2. downstream re-exports or in some other way links to env_logger
3. A user or developer of downstream builds documentation locally with cargo doc --no-deps (without --extern-html-root-url, because in practice no one but docs.rs does that).

Then the links to env_logger will be broken. But there's a simple fix and the fix is to remove --no-deps. Is this really so common that it's worth recommending that library authors use html_root_url?

Note that I'm hoping to fix this properly in cargo instead: rust-lang/cargo#8296

[jyn514]

Note that this has nothing to do with docs.rs, docs.rs passes --extern-html-root-url which always overrides any html_root_url you declare yourself.

[BurntSushi]

I'm pretty sure this guideline was created in a time where not specifying html_root_url was more problematic than it is today. But I can't remember the details to be honest. I don't think I use it in any of my crates and I've never heard any complaints.

[jyn514]

Oh hmm - I think when it was originally written rustdoc didn't support --extern-html-root-url, so docs.rs did need it. But that's not the case any more.

Should I make a PR removing the recommendation?

[jyn514]

Oh heh - it has a comment pointing to rust-lang/rust#42301, which I closed as wontfix a few days ago.

[BurntSushi]

Oh hmm - I think when it was originally written rustdoc didn't support --extern-html-root-url, so docs.rs did need it. But that's not the case any more.

Should I make a PR removing the recommendation?

I'm not even sure docs.rs was even around back then. But I can't remember. :)

[jhpratt]

For what it's worth I'm fairly certain most crates (including all of mine) don't use this attribute, and I have never had an issue with links not working exactly as expected.

[KodrAus]

Sounds like we should remove the recommendation then! It's a bit of a footgun that we don't need anymore.

[KodrAus]

Actually, since we have just been talking about the way we make decisions on this repo I should try actually follow what we set out and kick off an FCP!

[KodrAus]

@rfcbot fcp merge

I propose we remove the guideline recommending html_root_url as it's no longer necessary.

[KodrAus]

Guess I'd better go find out why @rfcbot doesn't want to hang out here

[rfcbot]

Team member @KodrAus has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @KodrAus
• @dtolnay
• @m-ou-se
• @sfackler
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[jyn514]

👀 @rfcbot unchecked @BurntSushi 's checkbox

[BurntSushi]

Weird. I just checked it again.

[KodrAus]

Oh wow... It did work 😮

[KodrAus]

Also note there was some lengthy discussion in #230 about this and its implications for non-Cargo build systems.

[Kage-Yami]

I'll agree it makes sense to reduce the effort involved in making a "good" library, but is there some alternative that keeps these links (even to local documentation of dependencies, if need be), without cluttering the left-hand side?

Yes, -Z rustdoc-map: rust-lang/cargo#8296

Given I work solely in Stable, effectively no... but I've watched that issue now (I missed the reference in the OP before).

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

psst @KodrAus, I wasn't able to add the final-comment-period label, please do so.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

psst @KodrAus, I wasn't able to add the finished-final-comment-period label, please do so.

[mgeisler]

I also frequently build with --no-deps, but at the same time tend to forget to update the html_root_url when cutting new releases so I've started removing them.

As a side-note: that is why I created the version-sync crate. It makes it trivial to add an integration test which will fail if you forget to update the html_root_url (or any other piece of text which mentions the version number).

[jplatte]

#230 was merged, this can be closed.