A tool for documenting Rust.
NOTE: This is not the "real"
rustdoc
. This is a prototype of a possible 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 into the target\doc
directory. Open
target\doc\index.html
to check it out.
There are three top-level directories that are important: src
contains the main source
code for rustdoc
. However, it will grab HTML, CSS, and JS from the frontend
directory,
which is where all of that stuff is developed. Finally, the example
directory contains
a sample crate that you can use to try out rustdoc
; we add stuff to it as we add support
for various things into rustdoc
itself.
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 generates a sort of "docs AST"; starting at the root of your crate and branching from there.
- It converts this "docs AST" to JSON, more specifically, JSON API.
- It writes out this JSON to the
target\doc
directory of the crate that it's documenting. - It writes out some HTML/CSS/JS from the frontend
target\doc
too.
Well, this is how it's going to work, anyway: the code isn't exactly super clean at the moment. More work to do!
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.
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.