A tool for documenting Rust.
NOTE: This is not the "real"
rustdoc
. This is a prototype of it's replacement. Therustdoc
you get with Rust lives in the Rust repo, in thesrc/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.
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.
There are a few top-level directories that are important:
src
contains the source code forrustdoc
. It includes two binaries: the backend (rustdoc
) and the bundled frontend (rustdoc-ember
).rustdoc-ember
will embed the HTML, CSS, and JS from thefrontend
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 inrustdoc
. It tests the JSON generated byrustdoc
for consumption by frontend binaries. Comment annotations are used to test various assertions. - The
example
directory contains a sample crate that you can try outrustdoc
with.
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:
- It shells out to
cargo
to generate "save analysis files", which are placed intarget/rls
. - 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! - It goes through the processed information and turns that data into a
Document
struct that contains the top-level crate information, and aVec<Document>
that contains data on all the submodules and their documented items. - 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. - 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 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.
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 anindex.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.
To build and view documentation:
cargo build --all --release
cargo run --release --bin rustdoc -- --manifest-path=example/Cargo.toml open
- "javascript error: data.json isn't found": go to
example/target/doc
and then runpython -m SimpleHTTPServer
(orpython -m http.server
if you are using python 3). Then go to the given URL above.
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:
rustdoc
is dual licensed under the MIT and Apache 2.0 licenses, and so contributions are also licensed under both.- Contributions go through pull requests to the
master
branch. - Check out the issue tracker to follow the
development of
rustdoc
.
For more details, see the CONTRIBUTING.md
file.