| .TH RUSTDOC "1" "March 2014" "rustdoc 0.11.0" "User Commands" |
| .SH NAME |
| rustdoc \- generate documentation from Rust source code |
| .SH SYNOPSIS |
| .B rustdoc |
| [\fIOPTIONS\fR] \fIINPUT\fR |
| |
| .SH DESCRIPTION |
| This tool generates API reference documentation by extracting comments from |
| source code written in the Rust language, available at |
| <\fBhttps://www.rust-lang.org\fR>. It accepts several input formats and provides |
| several output formats for the generated documentation. |
| |
| .SH OPTIONS |
| |
| .TP |
| -r --input-format <val> |
| html or json (default: inferred) |
| .TP |
| -w --output-format <val> |
| html or json (default: html) |
| .TP |
| -o --output <val> |
| where to place the output (default: doc/ for html, doc.json for json) |
| .TP |
| --passes <val> |
| space-separated list of passes to run (default: '') |
| .TP |
| --no-defaults |
| don't run the default passes |
| .TP |
| --plugins <val> |
| space-separated list of plugins to run (default: '') |
| .TP |
| --plugin-path <val> |
| directory to load plugins from (default: /tmp/rustdoc_ng/plugins) |
| .TP |
| -L --library-path <val> |
| directory to add to crate search path |
| .TP |
| -h, --help |
| Print help |
| |
| .SH "OUTPUT FORMATS" |
| |
| The rustdoc tool can generate output in either an HTML or JSON format. |
| |
| If using an HTML format, then the specified output destination will be the root |
| directory of an HTML structure for all the documentation. Pages will be placed |
| into this directory, and source files will also possibly be rendered into it as |
| well. |
| |
| If using a JSON format, then the specified output destination will have the |
| rustdoc output serialized as JSON into it. This output format exists to |
| pre-compile documentation for crates, and for usage in non-rustdoc tools. The |
| JSON output is the following hash: |
| |
| { |
| "schema": VERSION, |
| "crate": ..., |
| "plugins": ..., |
| } |
| |
| The schema version indicates what the structure of crate/plugins will look |
| like. Within a schema version the structure will remain the same. The `crate` |
| field will contain all relevant documentation for the source being documented, |
| and the `plugins` field will contain the output of the plugins run over the |
| crate. |
| |
| .SH "EXAMPLES" |
| |
| To generate documentation for the source in the current directory: |
| $ rustdoc hello.rs |
| |
| List all available passes that rustdoc has, along with default passes: |
| $ rustdoc --passes list |
| |
| To precompile the documentation for a crate, and then use it to render html at |
| a later date: |
| $ rustdoc -w json hello.rs |
| $ rustdoc doc.json |
| |
| The generated HTML can be viewed with any standard web browser. |
| |
| .SH "SEE ALSO" |
| |
| rustc |
| |
| .SH "BUGS" |
| See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues. |
| |
| .SH "AUTHOR" |
| See \fBAUTHORS.txt\fR in the Rust source distribution. |
| |
| .SH "COPYRIGHT" |
| This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR |
| file in the rust source distribution. |