Hot reloading your cargo docs

Making doc writing easier

Polishing eBPF documentation

I've been working on 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 streamlined writing experience with cargo doc.

2 dependencies

The 2 major deps 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.

References

Written by