# Why use nightly for docs.rs? **URL:** \ **Category:** documentation\ **Created:** [February 28, 2024, 11:32pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409 "2024-02-28T23:32:54Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 28, 2024, 11:32pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/1 "2024-02-28T23:32:54Z")
The title basically says it. Let me give an illustrative example. ## Example I was recently [fixing a bug](https://github.com/servo/pathfinder/pull/548#event-11777496175) in `servo/pathfinder` which I came across only because I was compiling the [plotters](https://github.com/plotters-rs/plotters) crate with the current nightly compiler. This problem was not present in the `nightly-2024-02-01` version (maybe even some later versions, I did not check every). Since the development is mainly done on stable, this bug would not have been noticed at all. But when submitting a new version to [crates.io](http://crates.io) and trying to build it on [docs.rs](https://docs.rs) this process will fail since docs.rs uses a nightly compiler to build all crates. In general, I can appreciate that some features such as the `doc(cfg(...))` are only available on nightly and desirable for writing concise documentation. A possible fix would be to support multiple compilers (stable, nightly) which can be set in the `[package.metadata.docs.rs]` section of `Cargo.toml` but I do not know how much effort it would be. Considering all this, I do not intend to push for any immediate changes as I do not see too many actual problems but I find the choice a bit odd considering that safety and guarantees are a very high priority in this community in general (which I really appreciate btw). ## TLDR What is the reason to use the nightly compiler for docs.rs? Thanks for your insight. ---
**Author:** ![chrefr](https://avatars.discourse-cdn.com/v4/letter/c/e480ec/32.png) [@chrefr](https://internals.rust-lang.org/u/chrefr)\ **Post date:** [February 28, 2024, 11:50pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/2 "2024-02-28T23:50:12Z")
I think a proper fix is to stabilize `#[doc(cfg(...))]`. ---
**Author:** ![epage](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/epage/32/3171_2.png) [@epage](https://internals.rust-lang.org/u/epage)\ **Post date:** [February 29, 2024, 1:55am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/3 "2024-02-29T01:55:19Z")
Flipping this the other way around, why does a crate build on stable but not on any nightly? I'm assuming its from nightly auto-detection which imo should not be used. It should be an explicit choice to enable features that could be coupled with specific nightly versions. ---
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 29, 2024, 2:16am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/4 "2024-02-29T02:16:20Z")
I think that this argument does not capture what I was getting at. The nightly version of rustc is nightly for a reason: it is not stable. But the documentation for docs.rs depends on this toolchain which can only offer limited guarantees in terms of stability. I also had multiple occasions of compiler bugs in the nightly compiler (it even said so explicitly when panicking). This would mean that your crates' documentation build does depend on the most volatile version of your compiler toolchain and it could theoretically change specific behaviour from one day to another. I am not sure that if a crate does not build repeatedly on nightly, that we can really assume that something is going on. It is certainly worrying but I would not make any generalized statement here. This might depend on the specific problem. But I agree that with enabling nightly-specific features you pretty much enter this land of "unknown future changes" which might break your system. But at least at this point you made a concious choice. ---
**Author:** ![epage](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/epage/32/3171_2.png) [@epage](https://internals.rust-lang.org/u/epage)\ **Post date:** [February 29, 2024, 2:51am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/5 "2024-02-29T02:51:37Z")
> [@jpleyer](#): > > The nightly version of rustc is nightly for a reason: it is not stable. But the documentation for docs.rs depends on this toolchain which can only offer limited guarantees in terms of stability. "stable" can mean different things. Are you concerned about bugs or changes in behavior of features behind flags? ---
**Author:** ![syphar](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/syphar/32/7788_2.png) [@syphar](https://internals.rust-lang.org/u/syphar)\ **Post date:** [February 29, 2024, 4:25am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/6 "2024-02-29T04:25:39Z")
Most of this was before my time, but from what I know the main reason to use nightly in docs.rs is that docs.rs is using some features in rustdoc that were specifically built for docs.rs, and only exist in nightly compilers. I’m not sure if it would be possible to make it work without these features, it would definitely involve a big chunk of work, and would slow down docs and/or reduce functionality. Or it would involve stabilizing features that are only used by docs.rs. There are some related issues: - [add option to build with stable](https://github.com/rust-lang/docs.rs/issues/506) - [specify nightly version to use for docs](https://github.com/rust-lang/docs.rs/issues/2358) ---
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 29, 2024, 8:44am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/7 "2024-02-29T08:44:11Z")
> [@epage](#): > > "stable" can mean different things. Are you concerned about bugs or changes in behavior of features behind flags? Both of the options you mentioned could be problematic. ---
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 29, 2024, 8:46am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/8 "2024-02-29T08:46:41Z")
Thanks for pointing this out. My initial question was mostly targeting if there is a rationale behind using nightly. I can understand that introducing all these options is much more tedious to maintain. ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [February 29, 2024, 9:31am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/9 "2024-02-29T09:31:09Z")
> [@jpleyer](#): > > The nightly version of rustc is nightly for a reason: it is not stable. This has not really been my experience exclusively developing with nightly locally for years (outside buggy dependencies enabling unstable features automatically). The number of breaking bugs on nightly releases in stable features has been similar to the number of breaking bug fixes in stable releases. Any bugs that do creep in have been fixed normally within a couple of days. ---
**Author:** ![Vorpal](https://avatars.discourse-cdn.com/v4/letter/v/aca169/32.png) [@Vorpal](https://internals.rust-lang.org/u/Vorpal)\ **Post date:** [February 29, 2024, 9:59am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/10 "2024-02-29T09:59:47Z")
I found that in CI the latest nightly breaks every few months. Not sure that it would affect doc generation, but it has been things like RISCV64 Linux suddenly being broken for a week, the MIPS build just disappearing etc (toolchain demoted to tier 3), bare metal targets breaking, etc. On x86-64 Linux (and presumably other tier 1 targets) it is pretty stable, but not everything targets only that. And "fixed within a couple of days" is kind of useless for docs.rs, since you then need to file a bug to get them to rerun your crate. Meanwhile your users can't actually check your API docs for your new version, since that is missing. They would have to build that locally. It would make a lot more sense for docs.rs to use latest stable (and they could stabilise the features needed, or use the env variable trick to use nightly on stable). For crates that use nightly features (rust-toolchain file) they could build those specific crates on nightly. But that is a vanishingly small number of crates these days (I would love to see some statistics on the percentage of crates that _need_ nightly on [crates.io](http://crates.io), grouped by year of publication). ---
**Author:** ![steffahn](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steffahn/32/13288_2.png) [@steffahn](https://internals.rust-lang.org/u/steffahn)\ **Post date:** [February 29, 2024, 11:59am UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/11 "2024-02-29T11:59:08Z")
> [@Vorpal](#): > > For crates that use nightly features (rust-toolchain file) they could build those specific crates on nightly. But that is a vanishingly small number of crates these days There's a few more crates offering _optional_ API that uses nightly features, and they would want that API be documented, too. Speaking of documenting optional API, there are crates that [use](https://github.com/tokio-rs/tokio/blob/5658d7c5032ade1bd0b18e3ec5b2b788eeac630e/tokio/src/macros/cfg.rs) unstable `rustdoc` [features](https://doc.rust-lang.org/rustdoc/unstable-features.html#doccfg-recording-what-platforms-or-features-are-required-for-code-to-be-present) to make those more readable, too. ---
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 29, 2024, 1:16pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/12 "2024-02-29T13:16:38Z")
> [@Vorpal](#): > > And "fixed within a couple of days" is kind of useless for docs.rs, since you then need to file a bug to get them to rerun your crate. Meanwhile your users can't actually check your API docs for your new version, since that is missing. They would have to build that locally. Yes this is also not a scalable setup considering that this community will probably grow further over the next years. ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [February 29, 2024, 2:24pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/13 "2024-02-29T14:24:54Z")
Once the build capacity is expanded it should be possible to setup automated or user-triggered rebuilds. This would help with more than just issues with nightly compiler bugs, it'd also help with situations like broken dependencies that have since published a fixed version that I think are a more common failure cause. One of the advantages of having docs.rs using nightly _is_ that it triggers these sorts of failures. It acts in some way as a more continuous form of crater, with more of an incentive to diagnose and fix the issues it finds. One of the things I keep meaning to work on (or at least sketch out a plan for) is a way to surface these issues to crate maintainers earlier, at the moment the only way really is to go check the page a bit after you publish a version to see if it failed or not. It should be possible to have some indication that there are issues with your crates when you visit any docs page. ---
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 29, 2024, 3:04pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/14 "2024-02-29T15:04:16Z")
> [@Nemo157](#): > > One of the advantages of having docs.rs using nightly _is_ that it triggers these sorts of failures. I strongly disagree with this statement. I my opinion crates should be tested **before** they are made publicly available under a new version. Publishing on docs.rs should (in my opinion) not act as additional CI. Otherwise I would like to schedule a new build whenever I push or get a PR. This is unrealistic in my opinion, simply from an infrastructure perspective as well. > [@Nemo157](#): > > One of the things I keep meaning to work on (or at least sketch out a plan for) is a way to surface these issues to crate maintainers earlier, at the moment the only way really is to go check the page a bit after you publish a version to see if it failed or not. Best case scenario: This never happenes. How can we avoid this? Make the build steps which are done by docs.rs _really_ obvious for end users. And make them as close to the default build steps that the most basic tools such as `cargo doc` already implements. The bigger this discrepancy without knowledge about it is, the more crates will start to fail. ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [February 29, 2024, 3:13pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/15 "2024-02-29T15:13:19Z")
> [@jpleyer](#): > > I strongly disagree with this statement. I my opinion crates should be tested **before** they are made publicly available under a new version. Publishing on docs.rs should (in my opinion) not act as additional CI. I'm talking about testing from the perspective of the Rust Project, not the crate that is being published. Testing against nightly is not something that I see that commonly done. > [@jpleyer](#): > > And make them as close to the default build steps that the most basic tools such as `cargo doc` already implements. The main place this differs (and where I see a decent proportion of the build failures come from) is user-configured `package.metadata.docs.rs`, which there's now a tool to parse and include in a build to make it trivial to test in CI: > **[GitHub - dtolnay/cargo-docs-rs: Imitate the documentation build that docs.rs...](https://github.com/dtolnay/cargo-docs-rs)** > > Imitate the documentation build that docs.rs would do - dtolnay/cargo-docs-rs ---
**Author:** ![jpleyer](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jpleyer/32/10849_2.png) [@jpleyer](https://internals.rust-lang.org/u/jpleyer)\ **Post date:** [February 29, 2024, 4:29pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/16 "2024-02-29T16:29:48Z")
> [@Nemo157](#): > > I'm talking about testing from the perspective of the Rust Project, not the crate that is being published. Testing against nightly is not something that I see that commonly done. Do you mean that you want to test the "backwards compatibility" of the nightly compiler? This still seems wild to do it in docs.rs. > [@Nemo157](#): > > The main place this differs (and where I see a decent proportion of the build failures come from) is user-configured `package.metadata.docs.rs`, which there's now a tool to parse and include in a build to make it trivial to test in CI: I was not aware of this new tools. It looks very interesting. I will surely test it. But there are also some other nuances. See my current PR: > > > This is a minor addition. Usually when working with the \`build crate -l\` command…, it is enough to apply it directly to the crate root. > However, when using cargo features such as inheritance of workspace settings (ie. \`version.workspace = true\`) it is necessary to package the crate first with \`cargo package\`. > > I am aware that the wording "package" should already make this clear. However, I stumbled across this problem personally and could not figure out the solution. Please correct me if I have overlooked any other documentation where this makes more sense. ---
**Author:** ![djc](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/djc/32/1592_2.png) [@djc](https://internals.rust-lang.org/u/djc)\ **Post date:** [February 29, 2024, 4:49pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/17 "2024-02-29T16:49:32Z")
Ultimately if we were building docs.rs today, it's not obvious to me that we would use nightly for this -- I think it's more of a historical artifact. IMO it would be nice to move docs.rs to stable at some point, since this would presumably make the output better suited for the vast majority of users. I don't know how tight the integration between rustdoc and docs.rs is at this point, and whether development velocity for docs.rs would suffer significantly from waiting for stable releases of rustdoc features it needs. ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [February 29, 2024, 6:02pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/18 "2024-02-29T18:02:32Z")
It probably would be good to actually make a tracking issue for all the unstable features in use, a quick skim shows: cargo features: - `-Zrustdoc-map` - to link to dependencies on docs.rs - `-Zhost-config`, `-Ztarget-applies-to-host` - to handle `package.metadata.docs.rs.rustc-args` when cross-compiling - `-Zrustdoc-scrape-examples` - somewhat as a form of stress-testing the feature rustdoc features (all these flags require `-Zunstable-options`): - `--emit`, `--static-root-path` - to split out the different varieties of artifacts and not replicate all the static files per-crate - `--resource-suffix` - to avoid filename overlap issues when rebuilding a crate with a newer rustdoc version e.g. the `search-index` I think still uses this, most uses were replaced by `--emit` and `--static-root-path` - `--extern-html-root-takes-precedence` - to ensure `#![doc(html_root_url = ...)]` doesn't cause off-site links - `--extern-html-root-url` - used under the hoods by `cargo -Zrustdoc-map` There's also explicit support for `package.metadata.docs.rs.cargo-args` containing `-Zbuild-std` to allow documenting for tier-3 targets. ---
**Author:** ![Nemo157](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/nemo157/32/11585_2.png) [@Nemo157](https://internals.rust-lang.org/u/Nemo157)\ **Post date:** [February 29, 2024, 6:06pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/19 "2024-02-29T18:06:35Z")
> [@djc](#): > > whether development velocity for docs.rs would suffer significantly from waiting for stable releases of rustdoc features it needs. This isn't really an issue, the unstable features in use change very rarely, and are mostly about improving on the interface rather than adding any new capability. It's more that some of these things that docs.rs needs to work have just been unstable for years, with no real motivation to get them stabilized when docs.rs is the only major user (some of them are likely useful for organizations building their own internal documentation sites, but I at least haven't heard anything about this usecase). ---
**Author:** ![notriddle](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/notriddle/32/14082_2.png) [@notriddle](https://internals.rust-lang.org/u/notriddle)\ **Post date:** [February 29, 2024, 6:25pm UTC](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409/20 "2024-02-29T18:25:43Z")
We do, occasionally, have docs.rs specific bugs. Mostly, it's because of the strange way it interfaces with rustdoc (patching HTML files to add its own nav bar, plus using CLI params that nobody else uses). If docs.rs hits one today, the solution is to land a fix in rustdoc, wait about a day, then rebuild all affected crates. The quicker we can catch it and release a fix, the less we have to rebuild. If docs.rs committed to using stable, how would a bug like that be fixed? A patch release of the compiler made specifically for docs.rs's benefit? A workaround that docs.rs has to carry for twelve weeks, followed by rebuilding twelve weeks' worth of crates before the workaround can be removed? [Next page](https://internals.rust-lang.org/t/why-use-nightly-for-docs-rs/20409.md?page=2)