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.
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
-ginstalls 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
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).
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
- 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.