set cfg(rustdoc) when rustdoc is running on a crate #53076

QuietMisdreavus · 2018-08-04T23:38:41Z

When using #[doc(cfg)] to document platform-specific items, it's a little cumbersome to get all the platforms' items to appear all at once. For example, the standard library adds --cfg dox to rustdoc's command line whenever it builds docs, and the documentation for #![feature(doc_cfg)] suggests using a Cargo feature to approximate the same thing. This is a little awkward, because you always need to remember to set --features dox whenever you build documentation.

This PR proposes making rustdoc set #[cfg(rustdoc)] whenever it runs on a crate, to provide an officially-sanctioned version of this that is set automatically. This way, there's a standardized way to declare that a certain version of an item is specifically when building docs.

To try to prevent the spread of this feature from happening too quickly, this PR also restricts the use of this flag to whenever #![feature(doc_cfg)] is active. I'm sure there are other uses for this, but right now i'm tying it to this feature. (If it makes more sense to give this its own feature, i can easily do that.)

r? @rust-lang/rustdoc (and maaaaaaybe someone from core? This seems a bit far-reaching...)

Mark-Simulacrum · 2018-08-04T23:53:55Z

I'll bring this up at core team triage next week if I don't forget.

GuillaumeGomez · 2018-08-05T11:46:12Z

Awesome!

nrc · 2018-08-05T20:24:36Z

SGTM. Also note that tools attributes are nearly stable (just waiting for a PR), so you can now use attributes of the form #[rustdoc::foo] however you like (and if there are any existing rustdoc attributes we might think about changing them to that form and deprecating the old ones).

nikomatsakis · 2018-08-09T20:11:06Z

cc @rust-lang/lang -- this PR is adding a #[cfg(rustdoc)] so that people can know that rustdoc is running and tweak their crate as needed. Seems fine to me but though y'all might like to be aware.

Mark-Simulacrum · 2018-08-09T20:12:26Z

We discussed this in Core team triage and the conclusion was to cc the lang team; we felt it wasn't really our field of purview at this point.

TimNN · 2018-08-14T16:28:42Z

I've added I-nominated to make sure the @rust-lang/lang team takes a look.

joshtriplett · 2018-08-14T17:00:32Z

This makes me a little nervous, but given that people can trivially do this themselves anyway, we might as well provide a sanctioned solution.

That said...I wonder if rustdoc could somehow handle platform-specific things more automatically, rather than requiring people to use cfg(rustdoc)? rustdoc could learn to "see through" cfg, automatically document everything, and provide some readable description of the platforms an item is available on.

QuietMisdreavus · 2018-08-14T17:38:29Z

@joshtriplett You have just described the oldest rustdoc issue on this tracker.

The biggest problem with "making rustdoc see through cfg" is that rustdoc isn't the one that's processing them. Rustc is. Rustdoc will happily try to show off everything that's given to it, if rustc can handle ignoring every #[cfg] attribute in a crate and still make it through macro expansion and name resolution. Making that happen is something i have called "the holy grail of rustdoc" because i'm pretty sure it will require way more work in the compiler then people are willing to deal with.

joshtriplett · 2018-08-14T17:46:11Z

@QuietMisdreavus Ah, I see. I didn't realize that, I thought this fell under the domain of rustdoc rather than rustc.

Centril · 2018-08-15T02:55:22Z

Seems fine to me; especially since it is feature gated. :)

joshtriplett · 2018-08-16T23:04:53Z

Chatted with @QuietMisdreavus about this at RustConf, and it seems reasonable. I'm going to go ahead and FCP this and see if anyone objects.

@rfcbot merge

rfcbot · 2018-08-16T23:04:54Z

onur · 2018-08-25T14:23:21Z

This is fine for me guys, maybe we can also set up a cfg(docsrs) for docs.rs, people have been asking me how they can differ build environment and do specific tasks for docs.rs.

QuietMisdreavus · 2018-08-25T14:42:19Z

@onur That should be fairly easy to set up, since you can add cfg flags via the command-line. We'd just need to add --cfg docsrs to the rustdoc flags whenever we call rustdoc over there and that should work out.

rfcbot · 2018-08-27T15:17:52Z

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

joshtriplett · 2018-08-27T15:21:26Z

Note: for this issue, I think it's appropriate to just treat the rfcbot coordination above as a poll for consensus, rather than seeking "FCP" specifically; I think the rustdoc team can simply proceed with this change at their discretion at this point.

joshtriplett · 2018-08-31T18:26:25Z

src/librustdoc/lib.rs

@@ -645,7 +645,7 @@ where R: 'static + Send,
        paths.add_path(s, ErrorOutputType::default());
    }
    let mut cfgs = matches.opt_strs("cfg");
-    cfgs.push("rustdoc");
+    cfgs.push("rustdoc".to_string());


Can you please squash this into the patch that introduced these lines?

GuillaumeGomez · 2018-09-01T09:33:42Z

Since everyone agreed, let's get it in then. Thanks @QuietMisdreavus!

@bors: r+

bors · 2018-09-01T09:33:43Z

📌 Commit ad2169c has been approved by GuillaumeGomez

…laumeGomez set cfg(rustdoc) when rustdoc is running on a crate When using `#[doc(cfg)]` to document platform-specific items, it's a little cumbersome to get all the platforms' items to appear all at once. For example, the standard library adds `--cfg dox` to rustdoc's command line whenever it builds docs, and the documentation for `#![feature(doc_cfg)]` suggests using a Cargo feature to approximate the same thing. This is a little awkward, because you always need to remember to set `--features dox` whenever you build documentation. This PR proposes making rustdoc set `#[cfg(rustdoc)]` whenever it runs on a crate, to provide an officially-sanctioned version of this that is set automatically. This way, there's a standardized way to declare that a certain version of an item is specifically when building docs. To try to prevent the spread of this feature from happening too quickly, this PR also restricts the use of this flag to whenever `#![feature(doc_cfg)]` is active. I'm sure there are other uses for this, but right now i'm tying it to this feature. (If it makes more sense to give this its own feature, i can easily do that.)

Rollup of 9 pull requests Successful merges: - #53076 (set cfg(rustdoc) when rustdoc is running on a crate) - #53622 (cleanup: Add main functions to some UI tests) - #53769 (Also link Clippy repo in the CONTRIBUTING.md file) - #53774 (Add rust-gdbgui script.) - #53781 (bench: libcore: fix build failure of any.rs benchmark (use "dyn Any")) - #53782 (Make Arc cloning mechanics clearer in module docs) - #53790 (Add regression test for issue #52060) - #53801 (Prevent duplicated impl on foreign types) - #53850 (Nuke the `const_to_allocation` query)

bors · 2018-09-01T18:08:36Z

⌛ Testing commit ad2169c with merge 839d99c...

This was added in rust-lang#53076 because several dependencies were using `cfg(dox)` instead of `cfg(rustdoc)`. I ran `rg 'cfg\(dox\)'` on the source tree with no matches, so I think this is now safe to remove.

@Mark-Simulacrum

Remove --cfg dox from rustdoc.rs This was added in rust-lang#53076 because several dependencies were using `cfg(dox)` instead of `cfg(rustdoc)` (now `cfg(doc)`). I ran `rg 'cfg\(dox\)'` on the source tree with no matches, so I think this is now safe to remove. r? @Mark-Simulacrum cc @QuietMisdreavus :)

Remove --cfg dox from rustdoc.rs This was added in rust-lang#53076 because several dependencies were using `cfg(dox)` instead of `cfg(rustdoc)` (now `cfg(doc)`). I ran `rg 'cfg\(dox\)'` on the source tree with no matches, so I think this is now safe to remove. r? `@Mark-Simulacrum` cc `@QuietMisdreavus` :)

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 4, 2018

kennytm added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-core Relevant to the core team, which will review and decide on the PR/issue. labels Aug 5, 2018

QuietMisdreavus added T-lang Relevant to the language team, which will review and decide on the PR/issue. and removed T-core Relevant to the core team, which will review and decide on the PR/issue. labels Aug 10, 2018

TimNN added I-nominated S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 14, 2018

Centril mentioned this pull request Aug 15, 2018

RFC: #[cfg(accessible(..) / version(..))] rust-lang/rfcs#2523

Merged

rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Aug 16, 2018

QuietMisdreavus force-pushed the cfg-rustdoc branch from b19428b to 23d87fe Compare August 22, 2018 14:37

rfcbot added the final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. label Aug 27, 2018

joshtriplett removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). I-nominated labels Aug 27, 2018

QuietMisdreavus added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 27, 2018

joshtriplett reviewed Aug 31, 2018

View reviewed changes

QuietMisdreavus added 3 commits August 31, 2018 13:29

feature(doc_cfg): set cfg(rustdoc) when rustdoc is running

1a3bb27

feature(doc_cfg): add docs for cfg(rustdoc)

d7e496f

use cfg(rustdoc) instead of cfg(dox) in std and friends

ad2169c

QuietMisdreavus force-pushed the cfg-rustdoc branch from 23d87fe to ad2169c Compare August 31, 2018 18:29

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 1, 2018

kennytm mentioned this pull request Sep 1, 2018

Rollup of 9 pull requests #53884

Merged

bors merged commit ad2169c into rust-lang:master Sep 1, 2018

rfcbot added finished-final-comment-period The final comment period is finished for this PR / Issue. and removed final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. labels Sep 6, 2018

Centril mentioned this pull request Oct 7, 2018

rustdoc or cargo doc should pass a special --cfg doc flag rust-lang/rfcs#915

Closed

This was referenced Dec 27, 2018

Feature Request: implement all the things from alga dimforge/nalgebra#511

Closed

Re-export alga docs to improve discoverability of trait implementations dimforge/nalgebra#512

Closed

Robbepop mentioned this pull request Mar 27, 2019

Generate special code for rustdoc compilations use-ink/ink#32

Closed

jmillikin mentioned this pull request Aug 8, 2020

cargo doc doesn't pass --cfg doc to rustc rust-lang/cargo#8601

Closed

jyn514 mentioned this pull request Sep 29, 2020

Remove --cfg dox from rustdoc.rs #77347

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

set cfg(rustdoc) when rustdoc is running on a crate #53076

set cfg(rustdoc) when rustdoc is running on a crate #53076

QuietMisdreavus commented Aug 4, 2018

Mark-Simulacrum commented Aug 4, 2018

GuillaumeGomez commented Aug 5, 2018

nrc commented Aug 5, 2018

nikomatsakis commented Aug 9, 2018

Mark-Simulacrum commented Aug 9, 2018

TimNN commented Aug 14, 2018

joshtriplett commented Aug 14, 2018

QuietMisdreavus commented Aug 14, 2018

joshtriplett commented Aug 14, 2018

Centril commented Aug 15, 2018

joshtriplett commented Aug 16, 2018

rfcbot commented Aug 16, 2018 •

edited by pnkfelix

Loading

onur commented Aug 25, 2018

QuietMisdreavus commented Aug 25, 2018

rfcbot commented Aug 27, 2018

joshtriplett commented Aug 27, 2018

joshtriplett Aug 31, 2018

QuietMisdreavus Aug 31, 2018

GuillaumeGomez commented Sep 1, 2018

bors commented Sep 1, 2018

bors commented Sep 1, 2018

set cfg(rustdoc) when rustdoc is running on a crate #53076

set cfg(rustdoc) when rustdoc is running on a crate #53076

Conversation

QuietMisdreavus commented Aug 4, 2018

Mark-Simulacrum commented Aug 4, 2018

GuillaumeGomez commented Aug 5, 2018

nrc commented Aug 5, 2018

nikomatsakis commented Aug 9, 2018

Mark-Simulacrum commented Aug 9, 2018

TimNN commented Aug 14, 2018

joshtriplett commented Aug 14, 2018

QuietMisdreavus commented Aug 14, 2018

joshtriplett commented Aug 14, 2018

Centril commented Aug 15, 2018

joshtriplett commented Aug 16, 2018

rfcbot commented Aug 16, 2018 • edited by pnkfelix Loading

onur commented Aug 25, 2018

QuietMisdreavus commented Aug 25, 2018

rfcbot commented Aug 27, 2018

joshtriplett commented Aug 27, 2018

joshtriplett Aug 31, 2018

Choose a reason for hiding this comment

QuietMisdreavus Aug 31, 2018

Choose a reason for hiding this comment

GuillaumeGomez commented Sep 1, 2018

bors commented Sep 1, 2018

bors commented Sep 1, 2018

rfcbot commented Aug 16, 2018 •

edited by pnkfelix

Loading