.TH RUSTDOC "1" "August 2015" "rustdoc 1.2.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
.UR https://www.rust\-lang.org
.UE .
It accepts several input formats and provides several output formats
for the generated documentation.

.SH OPTIONS

.TP
\fB\-r\fR, \fB\-\-input\-format\fR \fIFORMAT\fR
html or json (default: inferred)
.TP
\fB\-w\fR, \fB\-\-output\-format\fR \fIFORMAT\fR
html or json (default: html)
.TP
\fB\-o\fR, \fB\-\-output\fR \fIOUTPUT\fR
where to place the output (default: \fIdoc/\fR for html,
\fIdoc.json\fR for json)
.TP
\fB\-\-passes\fR \fILIST\fR
space\[hy]separated list of passes to run (default: '')
.TP
\fB\-\-no\-defaults\fR
don't run the default passes
.TP
\fB\-\-plugins\fR \fILIST\fR
space-separated list of plugins to run (default: '')
.TP
\fB\-\-plugin\-path\fR \fIDIR\fR
directory to load plugins from (default: \fI/tmp/rustdoc_ng/plugins\fR)
.TP
\fB\-\-target\fR \fITRIPLE\fR
target triple to document
.TP
\fB\-\-crate\-name\fR \fINAME\fR
specify the name of this crate
.TP
\fB\-L\fR, \fB\-\-library\-path\fR \fIDIR\fR
directory to add to crate search path
.TP
\fB\-\-cfg\fR \fISPEC\fR
pass a \fI\-\-cfg\fR to rustc
.TP
\fB\-\-extern\fR \fIVAL\fR
pass an \fI\-\-extern\fR to rustc
.TP
\fB\-\-test\fR
run code examples as tests
.TP
\fB\-\-test\-args\fR \fIARGS\fR
pass arguments to the test runner
.TP
\fB\-\-html\-in\-header\fR \fIFILE\fR
file to add to <head>
.TP
\fB\-\-html\-before\-content\fR \fIFILE\fR
file to add in <body>, before content
.TP
\fB\-\-html\-after\-content\fR \fIFILE\fR
file to add in <body>, after content
.TP
\fB\-\-markdown\-css\fR \fIFILE\fR
CSS files to include via <link> in a rendered Markdown file
.TP
\fB\-\-markdown\-playground\-url\fR \fIURL\fR
URL to send code snippets to
.TP
\fB\-\-markdown\-no\-toc\fR
don't include table of contents
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help
.TP
\fB\-V\fR, \fB\-\-version\fR
Print rustdoc's version

.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\[hy]compile documentation for crates,
and for usage in non\[hy]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 \fIcrate\fR field will contain all relevant documentation for the
source being documented, and the \fIplugins\fR 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"

.BR rustc (1)

.SH "BUGS"
See
.UR https://github.com/rust\-lang/rust/issues
.UE
for issues.

.SH "AUTHOR"
See \fIAUTHORS.txt\fR in the Rust source distribution.

.SH "COPYRIGHT"
This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
See \fICOPYRIGHT\fR file in the rust source distribution.