Rust doc hacking cheatsheet

gistfile1.md

Tips for hacking on Rust docs in the Rust tree

Standalone docs

• make doc/tutorial.html - build the tutorial
• make check-stage1-doc-tutorial - test the examples in the tutorial

API docs

• make doc/std/index.html - build the API docs for std
• make check-stage1-doc-crate-std - test std

Other stuff

• rm tmp/*ok - delete previous test results. The test runner will not run if it thinks the tests have already been completely successfully. Run this to reset.
• Add NO_REBUILD=1 to avoid rebuilding Rust when making changes to API docs or tests
• Add TESTNAME=foo to your make command to limit the set of tests being run.

NO_REBUILD=1 allows docs and tests to be built and run without recompiling Rust. This is useful for iterating on docs and tests in the standard libraries without lengthy rebuilds.

e.g. a typical command I might use for iterating on docs is rm tmp/*ok; make check-stage1-doc-crate-std NO_REBUILD=1 TESTNAME=io::net

Example

To work on the tutorial do the following:

1. make - Build Rust so all the tooling is ready
2. Edit src/doc/tutorial.md
3. Run make doc/tutorial.html NO_REBUILD=1 to build the doc
4. Run make check-stage1-doc-tutorial NO_REBUILD=1 to test the examples
5. Goto 2