Hot reloading your cargo docs

Making doc writing easier

I've been recently working on (soon to be oss) eBPF-related Rust libraries and part of the finishing touches has been making sure the docs come out polished as well. The tooling here has allowed me to have a simple, yet streamlined writing experience with cargo doc.

2 deps

The two major dependencies you'll need to set up this workflow are:

• cargo-watch: To install, run cargo install cargo-watch. This plugin is meant to be able to run tasks when your crate's src is updated.
• browser-sync: You'll need Node.js. To install, run npm i -g browser-sync (the -g installs the dependency globally, like cargo). This is what actually performs the seamless browser reloading in the background. This cli is way fancier than I expected it to be. It even comes with an internal UI!

Sync those docs

The two commands you'll want to run in parallel are:

browser-sync ./target/doc -w

This sets up browser-sync to not only set up a simple static server at that specified directory, but also with -w watches those files to send the reload event to the browser. Note that the path to docs may change depending on your crate setup. For example, in cargo workspaces your path to docs may be ../target/doc.

cargo watch -s 'cargo doc'

This generates the new docs as you write them.

To run these in parallel, you can either choose to run them in different terminals or send the first one you run to the background (my preference).

Voila!

You should now have hot reloading of your cargo docs. Fire up that editor and watch a live preview of your changes.

Btw, if you're into eBPF

Currently, I'm focused on developing tooling for eBPF with Rust. Follow me on the tweeters @mdaverde as I keep open sourcing and writing about my progress.

References

• Writing crate documentation
• The rustdoc book
• Browsersync docs
• cfg(doctest) is stable and you should use it

If you see any inaccuracies, typos or have comments, please reach out @mdaverde.