Skip to content

Instantly share code, notes, and snippets.

@brson

brson/gist:9470739

Last active February 15, 2016 04:15
Show Gist options
  • Save brson/9470739 to your computer and use it in GitHub Desktop.
Save brson/9470739 to your computer and use it in GitHub Desktop.
Download ZIP
Rust doc hacking cheatsheet
Raw
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment