btwiuse/cargo-docs

📗Serve rust and crate docs locally

cargo-docs

A cargo plugin for serving rust and crate doc locally.

$ cargo docs --help
Usage: cargo docs [OPTIONS] [EXTRA_ARGS]...

Arguments:
  [EXTRA_ARGS]...  Passthrough extra args to `cargo doc`

Options:
      --host <HOST>                    Set host [env: HOST=] [default: 127.0.0.1]
  -p, --port <PORT>                    Set port [env: PORT=] [default: 8080]
  -r, --random-port                    Use random port [env: CARGO_DOCS_RANDOM_PORT=true]
  -s, --search <ITEM>                  Search for item
  -d, --dir <DIR>                      Serve directory content [env: DIR=]
  -c, --manifest-path <MANIFEST_PATH>  Crate manifest path [default: Cargo.toml]
  -w, --watch                          Re-generate doc on change [env: CARGO_DOCS_WATCH=]
  -o, --open                           Open in browser [env: CARGO_DOCS_OPEN=true]
  -b, --book                           Serve rust book and std doc instead
  -h, --help                           Print help information
  -V, --version                        Print version information

By default, it will call cargo doc to build crate doc and start a local server.

Add --book option to see rust doc instead.

Install

$ cargo install cargo-docs

Examples

Serve crate doc on random port and open in browser

$ cargo docs -ro
[INFO] Serving crate doc on http://127.0.0.1:45669
[INFO] Opening http://127.0.0.1:45669

Same as above plus automatically rebuild and reload on file changes.

$ cargo docs -row
[INFO] Listening for changes...
[INFO] Serving crate doc on http://127.0.0.1:45669
[INFO] Opening http://127.0.0.1:45669

Serve rust docs instead (roughly the same as cargo-book)

$ cargo docs -bro
[INFO] Serving rust doc on http://127.0.0.1:46661
[INFO] Opening http://127.0.0.1:46661

Search for SocketAddr in rust std doc served on random port and open it in browser

$ cargo docs -bros SocketAddr
[INFO] Serving rust doc on http://127.0.0.1:40143
[INFO] Opening http://127.0.0.1:40143/std/?search=SocketAddr

Pro Tips

Passthrough cargo doc options after --

$ cargo docs -- --quiet
[INFO] Running cargo doc --quiet
[INFO] Serving crate doc on http://127.0.0.1:8080

If you are on WSL2, set BROWSER=/mnt/c/Path/To/Your/Browser.exe environment variable to open in desktop browser

$ export BROWSER="/mnt/c/Program Files/Firefox Nightly/firefox.exe"

Tired of typing -o, -ro, -row? Try these environment variables to save you some key strokes.

$ export CARGO_DOCS_OPEN=true
$ export CARGO_DOCS_WATCH=true
$ export CARGO_DOCS_RANDOM_PORT=true

cargo-docs's Issues

Seems to (accidentally?) depend on nightly

Great tool; t solves a long-standing open issue in rustdoc :)
It seems that it depends on the nightly compiler though. This is not really documented.
Maybe it is by accident?

$ cargo install cargo-docs
    Updating crates.io index
  Downloaded cargo-docs v0.1.19
  Downloaded 1 crate (20.3 KB) in 0.43s
  Installing cargo-docs v0.1.19
  ...
   Compiling dump v0.1.1
error[E0554]: `#![feature]` may not be used on the stable release channel
 --> [snip]/.cargo/registry/src/github.com-1ecc6299db9ec823/dump-0.1.1/src/lib.rs:1:12
  |
1 | #![feature(core_intrinsics)]
  |      

Live reloading

Automatically reload the website when the content changes.

trunk supports this using this js: https://github.com/thedodd/trunk/blob/master/src/autoreload.js and the rust part should be somewhere around here: https://github.com/thedodd/trunk/blob/master/src/serve.rs#L200-L208 .

broken on paritytech/substrate

I've used cargo-docs for quite some time successfully for the work I do on https://github.com/paritytech/substrate however recently this stopped working. Running cargo docs on a recent version of master will result in thousands of cascading errors such as:

[INFO] fingerprint error for pallet-root-offences v1.0.0-dev (/Users/sam/workspace/substrate/frame/root-offences)/Doc { deps: true }/TargetInner { ..: lib_target("pallet-root-offences", ["lib"], "/Users/sam/workspace/substrate/frame/root-offences/src/lib.rs", Edition2021) }
[INFO]     err: target configuration has changed
[INFO] fingerprint error for pallet-scored-pool v4.0.0-dev (/Users/sam/workspace/substrate/frame/scored-pool)/Doc { deps: true }/TargetInner { ..: lib_target("pallet-scored-pool", ["lib"], "/Users/sam/workspace/substrate/frame/scored-pool/src/lib.rs", Edition2021) }
[INFO]     err: target configuration has changed
[INFO] fingerprint error for pallet-session-benchmarking v4.0.0-dev (/Users/sam/workspace/substrate/frame/session/benchmarking)/Doc { deps: true }/TargetInner { ..: lib_target("pallet-session-benchmarking", ["lib"], "/Users/sam/workspace/substrate/frame/session/benchmarking/src/lib.rs", Edition2021) }
[INFO]     err: target configuration has changed
[INFO] fingerprint error for pallet-staking-reward-fn v4.0.0-dev (/Users/sam/workspace/substrate/frame/staking/reward-fn)/Doc { deps: true }/TargetInner { ..: lib_target("pallet-staking-reward-fn", ["lib"], "/Users/sam/workspace/substrate/frame/staking/reward-fn/src/lib.rs", Edition2021) }
[INFO]     err: target configuration has changed
[INFO] fingerprint error for sc-consensus-manual-seal v0.10.0-dev (/Users/sam/workspace/substrate/client/consensus/manual-seal)/Doc { deps: true }/TargetInner { ..: lib_target("sc-consensus-manual-seal", ["lib"], "/Users/sam/workspace/substrate/client/consensus/manual-seal/src/lib.rs", Edition2021) }
[INFO]     err: target configuration has changed

etc.

To reproduce, simply try running cargo docs on master on that repo and you'll see what I mean.

Notably this only happens when running cargo docs whereas running cargo doc works just fine.

Web server takes a very long time to load and no indication of it loading

I've noticed it will say it's serving from [IP address] but it's not for another minute or two that the server comes up. Would be great if there was some visual indication in the output when the server is actually available. Also not sure why it is so slow to launch. Seems to happen on all my machines so I don't think it's anything particular on my end.