dtolnay / cargo-docs-rs

Imitate the documentation build that docs.rs would do

cargo docs-rs

Run cargo rustdoc with the same options that would be used by docs.rs, taking into account the package.metadata.docs.rs configured in Cargo.toml.

Example

If the following GitHub Actions job succeeds, it's likely that docs.rs will succeed in building your crate's documentation.

# .github/workflows/ci.yml

name: test suite
on: [push, pull_request]

jobs:
  # ...

  doc:
    name: Documentation
    runs-on: ubuntu-latest
    env:
      RUSTDOCFLAGS: -Dwarnings
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@nightly
      - uses: dtolnay/install@cargo-docs-rs
      - run: cargo docs-rs

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

cargo-docs-rs's Issues

Failed to parse output of `cargo metadata`

$ git clone https://github.com/wcampbell0x2a/backhand.git
$ cd backhand
$ cargo --version
cargo 1.76.0-nightly (1aa9df1a5 2023-12-12)
$ cargo docs-rs --open
Error: Failed to parse output of `cargo metadata`

Caused by:
    invalid type: string "all", expected a sequence at line 1 column 632149

cfg(docsrs) isn't being set properly?

Example:

#[cfg(docsrs)]
compile_error!("cfg(docsrs) set");

#[cfg(not(docsrs))]
compile_error!("cfg(docsrs) not set");

> cargo +nightly docs-rs --verbose
       Dirty cstr8 v0.1.3 (D:\git\cad97\cstr8): the precalculated components changed
 Documenting cstr8 v0.1.3 (D:\git\cad97\cstr8)
     Running `rustdoc --edition=2021 --crate-type lib --crate-name cstr8 src\lib.rs -o D:\.rust\target\doc --cfg "feature=\"alloc\"" --cfg "feature=\"default\"" --cfg "feature=\"std\"" --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=119 -C metadata=2fab72609bfd58bc -L dependency=D:\.rust\target\debug\deps --crate-version 0.1.3`
error: cfg(docsrs) not set
  --> src\lib.rs:28:1
   |
28 | compile_error!("cfg(docsrs) not set");
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: could not document `cstr8`

> $env.RUSTDOCFLAGS = "--cfg=docsrs"
> cargo +nightly doc --verbose
       Dirty cstr8 v0.1.3 (D:\git\cad97\cstr8): the profile configuration changed
 Documenting cstr8 v0.1.3 (D:\git\cad97\cstr8)
     Running `rustdoc --edition=2021 --crate-type lib --crate-name cstr8 src\lib.rs -o D:\.rust\target\doc --cfg "feature=\"alloc\"" --cfg "feature=\"default\"" --cfg "feature=\"std\"" --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=119 -C metadata=6c16e02dedfb218b -L dependency=D:\.rust\target\debug\deps --cfg=docsrs --crate-version 0.1.3`
error: cfg(docsrs) set
  --> src\lib.rs:25:1
   |
25 | compile_error!("cfg(docsrs) set");
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: could not document `cstr8`

> cargo +nightly docs-rs --version
cargo-docs-rs 0.1.10

Attempting to diagnose, this seems to be caused by -Zhost-config, as removing that flag from the execution results in --cfg=docsrs being included in the rustdoc invocation.

> cargo +nightly rustdoc --verbose -Zunstable-options --config 'build.rustdocflags=["--cfg=docsrs"]' -Ztarget-applies-to-host
       Dirty cstr8 v0.1.3 (D:\git\cad97\cstr8): the rustflags changed
 Documenting cstr8 v0.1.3 (D:\git\cad97\cstr8)
     Running `rustdoc --edition=2021 --crate-type lib --crate-name cstr8 src\lib.rs -o D:\.rust\target\doc --cfg "feature=\"alloc\"" --cfg "feature=\"default\"" --cfg "feature=\"std\"" --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=119 -C metadata=2fab72609bfd58bc -L dependency=D:\.rust\target\debug\deps --cfg=docsrs --crate-version 0.1.3`
error: cfg(docsrs) set
  --> src\lib.rs:25:1
   |
25 | compile_error!("cfg(docsrs) set");
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> cargo +nightly rustdoc --verbose -Zunstable-options --config 'build.rustdocflags=["--cfg=docsrs"]' -Ztarget-applies-to-host -Zhost-config
       Dirty cstr8 v0.1.3 (D:\git\cad97\cstr8): the config settings changed
 Documenting cstr8 v0.1.3 (D:\git\cad97\cstr8)
     Running `rustdoc --edition=2021 --crate-type lib --crate-name cstr8 src\lib.rs -o D:\.rust\target\doc --cfg "feature=\"alloc\"" --cfg "feature=\"default\"" --cfg "feature=\"std\"" --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=119 -C metadata=2fab72609bfd58bc -L dependency=D:\.rust\target\debug\deps --crate-version 0.1.3`
error: cfg(docsrs) not set
  --> src\lib.rs:28:1
   |
28 | compile_error!("cfg(docsrs) not set");
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> cargo +nightly -Vv
cargo 1.78.0-nightly (f772ec022 2024-03-01)
release: 1.78.0-nightly
commit-hash: f772ec0224d3755ce52ac5128a80319fb2eb45d0
commit-date: 2024-03-01
host: x86_64-pc-windows-msvc
libgit2: 1.7.2 (sys:0.18.2 vendored)
libcurl: 8.6.0-DEV (sys:0.4.72+curl-8.6.0 vendored ssl:Schannel)
os: Windows 10.0.22631 (Windows 11 Education) [64-bit]

That might mean this is an upstream issue but I legitimately don't know and this is where I ran into it.