Live Refreshing Cargo Docs

rustdoc is a great tool, but as of now there isn’t an official way to have its generated docs refresh as you make edits. Running cargo doc with the --open argument will open the generated docs in browser window. If you make changes to your source code, you’ll need to re-run cargo doc to have the changes reflected in your browser. By chaining together a few other Rust tools, we can pretty easily get the functionality of live-reloading docs.

We’ll be 2 tools:

• cargo-watch to watch when our project’s source has changed and trigger the docs rebuild.
• http as a static server for the generated docs.
  • This isn’t strictly necessary: As mentioned earlier, you can use the --open argument with cargo doc to view docs using the file:// protocol, but I like having a localhost address to visit.

I’ll assume that you already have cargo installed. If you don’t, then you can use rustup to install it.

Step 1: Install cargo-watch and https

First, install both commands we’ll need:

cargo install cargo-watch https

Step 2: Run Watch Command

Now, navigate to the project directory that contains your Cargo.toml file. Then, run the following:

cargo watch -s 'cargo doc && http target/doc'

You should now see something like the following:

[Running cargo doc && http target/doc]
 Documenting docs-example v0.1.0 (file:///path/to/project/docs-example)
    Finished dev [unoptimized + debuginfo] target(s) in 0.43s
Hosting "target/doc" on port 8000 without TLS...
Ctrl-C to stop.

You can visit localhost:8000 in your browser to view the generated docs. (Note: you’ll initially see a directory page, so you’ll have to navigate to one of the package listings to see actual docs)

If you make any changes to any source file in your project, you’ll see that cargo-watch will automatically re-run cargo doc and restart the file server. You should be able to refresh your browser and see the documentation changes live.

Bonus: Auto-refresh

One annoyance with this approach is that editing a source file does not trigger a refresh in the browser (i.e. you still have to refresh the page manually).

If you’re fine with using a node-based tool, browser-sync fixes this problem.

Install with:

npm install -g browser-sync

… then edit your cargo-watch command to use browser-sync instead of http:

cargo watch -s 'cargo doc && browser-sync start --ss target/doc -s target/doc --directory --no-open'

Now, visit localhost:3000 (or whichever port is listed on startup). Any subsequent changes to your Rust source code will now trigger any open browsers to refresh automatically with the updated documentation.

I’ve found that using this tweak to have auto-refreshing docs makes it much more pleasant to document my Rust crates. I’d love to see if there’s a more streamlined way to have auto-refreshing docs – be sure to let me know! 😄

More Information

• To learn the basics of rustdoc (which powers cargo doc), check this chapter in the rust book.
• These issues give context as to why this functionality isn’t officially supported (as of now): cargo#1472, cargo#4966