ehuss / rustdoc

A documentation tool for Rust.

rustdoc

A tool for documenting Rust.

NOTE: This is not the "real" rustdoc. This is a prototype of it's replacement. The rustdoc you get with Rust lives in the Rust repo, in the src/librustdoc directory.

Specifically, you can run rustdoc inside the root of a crate, and it will produce HTML, CSS, and Javascript. It will then put them into the target/doc directory. Open target/doc/index.html to check it out.

Purpose

The current rustdoc tool is a wonderful tool for Rust developers, giving us the ability to write great docs for our code. But it has one big downside that it uses the compiler's internals to generate the docs and this in turn makes it difficult to contribute to the docs. Essentially, one has to setup the entire compiler toolchain in order to modify/add new features to the tool. While we recognize that there are lots of improvements we can do to the rustdoc tool, we first need to make a separate repository and have it achieve feature parity with the current docs by building it from the ground up. Having said that this is not the only purpose of this project and we plan to add more features once the feature parity is achieved. Take a look at The Rustdoc Redux for more information about the purpose of this project.

Project structure

There are a few top-level directories that are important:

• src contains the source code for rustdoc. It includes two binaries: the backend (rustdoc) and the bundled frontend (rustdoc-ember). rustdoc-ember will embed the HTML, CSS, and JS from the frontend directory in the final binary.
• Any presentation of the documentation (such as layout and how it works) is found in the frontend directory.
• The tests directory contains tests for things we've added support for in rustdoc. It tests the JSON generated by rustdoc for consumption by frontend binaries. Comment annotations are used to test various assertions.
• The example directory contains a sample crate that you can try out rustdoc with.

The backend

The backend, located in src, is written in Rust. rustdoc is effectively a compiler, but instead of compiling source code to machine code, it compiles source code to JSON. Here's how it does it:

1. It shells out to cargo to generate "save analysis files", which are placed in target/rls.
2. It reads those save analysis files with the rls-analysis crate. As you may be able to guess from the name, this is pretty much why it exists!
3. It goes through the processed information and turns that data into a Document struct that contains the top-level crate information, and a Vec<Document> that contains data on all the submodules and their documented items.
4. These two pieces are turned into a Documentation struct which is immediately serialized to JSON, specifically, a subset of JSON API as we don't need all of the items used in the spec.
5. It shells out to a frontend binary, writing the documentation JSON to stdin. The frontend is expected to write out HTML, CSS, JS, etc. to target/doc.

You can also request it write out some or all of these artifacts through the --emit flag.

The frontend

The frontend is currently implemented with Ember. Its source code is in the frontend directory.

The first thing that the frontend does is in frontend/app/routes/application.js. This route runs before anything else, and it makes a request to grab a data.json file, which is generated by the back end. This loads up all of the docs into ember-data, which drives the rest of the site.

One other slightly unusual aspect of the frontend: normally, you'd have the dist directory ignored, as you don't want to commit generated files. In this case, though, we don't want ember to be a dependency of installing rustdoc, and so we do commit those generated files. They are bundled in the rustdoc-ember binary.

Alternative Frontends

rustdoc allows using alternative frontends, provided that the frontend conforms to a particular interface.

• The frontend must read its input from stdin. rustdoc will pipe the documentation JSON generated by the backend into the frontend as a subprocess.
• The frontend must allow an --output <path> argument, for specifying where the frontend should output its files.
• The frontend is free to generate whatever files it pleases in the output directory, but rustdoc expects that frontends generate an index.html file at the root or the crate root (crate_name/index.html).

To use an alternative frontend, set the RUSTDOC_FRONTEND environment variable to a path to a frontend binary.

Usage

To build and view documentation:

cargo build --all --release
cargo run --release --bin rustdoc -- --manifest-path=example/Cargo.toml open

Known issues (and their solution)

• "javascript error: data.json isn't found": go to example/target/doc and then run python -m SimpleHTTPServer (or python -m http.server if you are using python 3). Then go to the given URL above.

Contributing

We'd love your help with making rustdoc better! It's currently very early days, so there's a lot to do. Here's a quick overview:

1. rustdoc is dual licensed under the MIT and Apache 2.0 licenses, and so contributions are also licensed under both.
2. Contributions go through pull requests to the master branch.
3. Check out the issue tracker to follow the development of rustdoc.

For more details, see the CONTRIBUTING.md file.