# rustdoc

**Repository Path**: mirrors_hjr3/rustdoc

## Basic Information

- **Project Name**: rustdoc
- **Description**: A documentation tool for Rust.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2025-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rustdoc

[![Build Status][travis_img]][travis] [![Windows build status][appveyor_img]][appveyor]

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][rust], 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][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][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][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][issue_tracker] to follow the
   development of `rustdoc`.

For more details, see the [`CONTRIBUTING.md`][contributing] file.

[travis]: https://travis-ci.org/steveklabnik/rustdoc
[travis_img]: https://travis-ci.org/steveklabnik/rustdoc.svg?branch=master
[appveyor]: https://ci.appveyor.com/project/steveklabnik/rustdoc
[appveyor_img]: https://ci.appveyor.com/api/projects/status/github/steveklabnik/rustdoc?svg=true
[rust]: https://github.com/rust-lang/rust
[rustdoc_redux]: https://internals.rust-lang.org/t/the-rustdoc-redux/5542
[json_api]: https://jsonapi.org
[ember]: https://emberjs.com/
[issue_tracker]: https://github.com/steveklabnik/rustdoc/issues
[contributing]: https://github.com/steveklabnik/rustdoc/blob/master/CONTRIBUTING.md