2014-10-09 17:41:23 +00:00
|
|
|
.TH RUSTDOC "1" "March 2014" "rustdoc 0.13.0" "User Commands"
|
2013-07-07 04:06:54 +00:00
|
|
|
.SH NAME
|
|
|
|
|
rustdoc \- generate documentation from Rust source code
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.B rustdoc
|
2013-09-30 20:28:30 +00:00
|
|
|
[\fIOPTIONS\fR] \fIINPUT\fR
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
This tool generates API reference documentation by extracting comments from
|
2013-09-30 20:28:30 +00:00
|
|
|
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.
|
2013-07-07 04:06:54 +00:00
|
|
|
|
2013-09-30 20:28:30 +00:00
|
|
|
.SH OPTIONS
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.TP
|
2013-09-30 20:28:30 +00:00
|
|
|
-r --input-format <val>
|
|
|
|
|
html or json (default: inferred)
|
2013-07-07 04:06:54 +00:00
|
|
|
.TP
|
2013-09-30 20:28:30 +00:00
|
|
|
-w --output-format <val>
|
|
|
|
|
html or json (default: html)
|
2013-07-07 04:06:54 +00:00
|
|
|
.TP
|
2013-09-30 20:28:30 +00:00
|
|
|
-o --output <val>
|
|
|
|
|
where to place the output (default: doc/ for html, doc.json for json)
|
2013-07-07 04:06:54 +00:00
|
|
|
.TP
|
2013-09-30 20:28:30 +00:00
|
|
|
--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
|
2015-01-17 19:45:59 +00:00
|
|
|
--target <val>
|
|
|
|
|
target triple to document
|
|
|
|
|
.TP
|
|
|
|
|
--crate-name <val>
|
|
|
|
|
specify the name of this crate
|
|
|
|
|
.TP
|
2013-09-30 20:28:30 +00:00
|
|
|
-L --library-path <val>
|
|
|
|
|
directory to add to crate search path
|
2013-07-07 04:06:54 +00:00
|
|
|
.TP
|
2015-01-17 19:45:59 +00:00
|
|
|
--cfg <val>
|
|
|
|
|
pass a --cfg to rustc
|
|
|
|
|
.TP
|
|
|
|
|
--extern <val>
|
|
|
|
|
pass an --extern to rustc
|
|
|
|
|
.TP
|
|
|
|
|
--test
|
|
|
|
|
run code examples as tests
|
|
|
|
|
.TP
|
|
|
|
|
--test-args <val>
|
|
|
|
|
pass arguments to the test runner
|
|
|
|
|
.TP
|
2014-06-28 10:35:25 +00:00
|
|
|
--html-in-header <val>
|
|
|
|
|
file to add to <head>
|
|
|
|
|
.TP
|
|
|
|
|
--html-before-content <val>
|
|
|
|
|
file to add in <body>, before content
|
|
|
|
|
.TP
|
|
|
|
|
--html-after-content <val>
|
|
|
|
|
file to add in <body>, after content
|
|
|
|
|
.TP
|
2015-01-17 19:45:59 +00:00
|
|
|
--markdown-css <val>
|
|
|
|
|
CSS files to include via <link> in a rendered Markdown file
|
|
|
|
|
.TP
|
|
|
|
|
--markdown-playground-url <val>
|
|
|
|
|
URL to send code snippets to
|
|
|
|
|
.TP
|
|
|
|
|
--markdown-no-toc
|
|
|
|
|
don't include table of contents
|
|
|
|
|
.TP
|
2013-07-07 04:06:54 +00:00
|
|
|
-h, --help
|
|
|
|
|
Print help
|
2015-01-17 19:45:59 +00:00
|
|
|
.TP
|
|
|
|
|
-V, --version
|
|
|
|
|
Print rustdoc's version
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH "OUTPUT FORMATS"
|
|
|
|
|
|
2013-09-30 20:28:30 +00:00
|
|
|
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.
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH "EXAMPLES"
|
|
|
|
|
|
|
|
|
|
To generate documentation for the source in the current directory:
|
|
|
|
|
$ rustdoc hello.rs
|
|
|
|
|
|
2013-09-30 20:28:30 +00:00
|
|
|
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
|
2013-07-07 04:06:54 +00:00
|
|
|
|
2013-09-30 20:28:30 +00:00
|
|
|
The generated HTML can be viewed with any standard web browser.
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
|
2014-02-02 07:56:55 +00:00
|
|
|
rustc
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH "BUGS"
|
2014-06-16 23:07:34 +00:00
|
|
|
See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues.
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH "AUTHOR"
|
2014-04-14 21:55:40 +00:00
|
|
|
See \fBAUTHORS.txt\fR in the Rust source distribution.
|
2013-07-07 04:06:54 +00:00
|
|
|
|
|
|
|
|
.SH "COPYRIGHT"
|
|
|
|
|
This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR
|
|
|
|
|
file in the rust source distribution.
|
