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 main source code for rustdoc. It will embed the HTML, CSS, and JS from the frontend directory, in the final binary.
• Any of the presentation of the documentation such as layout and how it works is found in that frontend directory.
• The tests directory contains tests for things we've added support for in rustdoc. It tests that the output of the JSON generated by rustdoc for the frontend is what it expects to get using comment annotations to test various assertions.
• The example directory contains a sample crate that you can use to try out with rustdoc; we add stuff to it as we add support for various things into rustdoc itself.

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 writes out this JSON to the target/doc directory of the crate that it's documenting.
6. It writes out some HTML/CSS/JS from the frontend to target/doc as well.

You can also request it to only write out some of this information 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.

Usage

Currently, it only builds the given example. Do it as follow:

cargo run --release -- --manifest-path=example/Cargo.toml

Then open a web browser and open "rustdoc/example/target/doc/index.html".

Known issues (and their solution)

• "javascript error: data.json isn't found": go to example/target/doc and then run python -m SimpleHTTPServer. 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.