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 withcargo doc
to view docs using thefile://
protocol, but I like having alocalhost
address to visit.
- This isn’t strictly necessary: As mentioned earlier, you can use the
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 powerscargo 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
Top comments (0)