# 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. <!--more-->

We'll be 2 tools:

- [cargo-watch](https://github.com/passcod/cargo-watch) to watch when our project’s source has changed and trigger the docs rebuild.
- [http](https://github.com/thecoshman/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](https://rustup.rs/) to install it.

### Step 1: Install `cargo-watch` and `https`
First, install both commands we’ll need:
```sh
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:
```sh
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](https://browsersync.io/) fixes this problem.

Install with:
```sh
npm install -g browser-sync
```

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

```sh
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](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html) in the rust book.
* These issues give context as to why this functionality isn’t officially supported (as of now): [cargo#1472](https://github.com/rust-lang/cargo/issues/1472), [cargo#4966](https://github.com/rust-lang/cargo/issues/4966)