mk: Update how the build deals with version labels. #16677
Adds a new configure flag, --release-channel, which determines how the version
number should be augmented with a release label, as well as how the distribution
artifacts will be named. This is entirely for use by the build automation.
--release-channel can be either 'source', 'nightly', 'beta', or 'stable'.
Here's a summary of the affect of these values on version number and
artifact naming, respectively:
* source - '0.12.0-pre', 'rust-0.12.0-pre-...'
* nightly - '0.12.0-nightly', 'rust-nightly-...'
* beta - '0.12.0-beta', 'rust-beta-...'
* stable - '0.12.0', 'rust-0.12.0-...'
Per http://discuss.rust-lang.org/t/rfc-impending-changes-to-the-release-process/508/1
2014-09-15 15:40:30 -05:00
|
|
|
.TH RUSTDOC "1" "March 2014" "rustdoc 0.12.0" "User Commands"
|
2013-07-06 23:06:54 -05:00
|
|
|
.SH NAME
|
|
|
|
|
rustdoc \- generate documentation from Rust source code
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.B rustdoc
|
2013-09-30 15:28:30 -05:00
|
|
|
[\fIOPTIONS\fR] \fIINPUT\fR
|
2013-07-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
This tool generates API reference documentation by extracting comments from
|
2013-09-30 15:28:30 -05: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-06 23:06:54 -05:00
|
|
|
|
2013-09-30 15:28:30 -05:00
|
|
|
.SH OPTIONS
|
2013-07-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.TP
|
2013-09-30 15:28:30 -05:00
|
|
|
-r --input-format <val>
|
|
|
|
|
html or json (default: inferred)
|
2013-07-06 23:06:54 -05:00
|
|
|
.TP
|
2013-09-30 15:28:30 -05:00
|
|
|
-w --output-format <val>
|
|
|
|
|
html or json (default: html)
|
2013-07-06 23:06:54 -05:00
|
|
|
.TP
|
2013-09-30 15:28:30 -05:00
|
|
|
-o --output <val>
|
|
|
|
|
where to place the output (default: doc/ for html, doc.json for json)
|
2013-07-06 23:06:54 -05:00
|
|
|
.TP
|
2013-09-30 15:28:30 -05: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
|
|
|
|
|
-L --library-path <val>
|
|
|
|
|
directory to add to crate search path
|
2013-07-06 23:06:54 -05:00
|
|
|
.TP
|
2014-06-28 05:35:25 -05: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
|
2013-07-06 23:06:54 -05:00
|
|
|
-h, --help
|
|
|
|
|
Print help
|
|
|
|
|
|
|
|
|
|
.SH "OUTPUT FORMATS"
|
|
|
|
|
|
2013-09-30 15:28:30 -05: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-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.SH "EXAMPLES"
|
|
|
|
|
|
|
|
|
|
To generate documentation for the source in the current directory:
|
|
|
|
|
$ rustdoc hello.rs
|
|
|
|
|
|
2013-09-30 15:28:30 -05: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-06 23:06:54 -05:00
|
|
|
|
2013-09-30 15:28:30 -05:00
|
|
|
The generated HTML can be viewed with any standard web browser.
|
2013-07-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
|
2014-02-02 01:56:55 -06:00
|
|
|
rustc
|
2013-07-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.SH "BUGS"
|
2014-06-16 18:07:34 -05:00
|
|
|
See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues.
|
2013-07-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.SH "AUTHOR"
|
2014-04-14 16:55:40 -05:00
|
|
|
See \fBAUTHORS.txt\fR in the Rust source distribution.
|
2013-07-06 23:06:54 -05:00
|
|
|
|
|
|
|
|
.SH "COPYRIGHT"
|
|
|
|
|
This work is dual-licensed under Apache 2.0 and MIT terms. See \fBCOPYRIGHT\fR
|
|
|
|
|
file in the rust source distribution.
|
