man/rustdoc.1

   1 .TH RUSTDOC "1" "March 2014" "rustdoc 0.11.0" "User Commands"
   2 .SH NAME
   3 rustdoc \- generate documentation from Rust source code
   4 .SH SYNOPSIS
   5 .B rustdoc
   6 [\fIOPTIONS\fR] \fIINPUT\fR
   7
   8 .SH DESCRIPTION
   9 This tool generates API reference documentation by extracting comments from
  10 source code written in the Rust language, available at
  11 <\fBhttps://www.rust-lang.org\fR>. It accepts several input formats and provides
  12 several output formats for the generated documentation.
  13
  14 .SH OPTIONS
  15
  16 .TP
  17 -r --input-format <val>
  18 html or json (default: inferred)
  19 .TP
  20 -w --output-format <val>
  21 html or json (default: html)
  22 .TP
  23 -o --output <val>
  24 where to place the output (default: doc/ for html, doc.json for json)
  25 .TP
  26 --passes <val>
  27 space-separated list of passes to run (default: '')
  28 .TP
  29 --no-defaults
  30 don't run the default passes
  31 .TP
  32 --plugins <val>
  33 space-separated list of plugins to run (default: '')
  34 .TP
  35 --plugin-path <val>
  36 directory to load plugins from (default: /tmp/rustdoc_ng/plugins)
  37 .TP
  38 -L --library-path <val>
  39 directory to add to crate search path
  40 .TP
  41 --html-in-header <val>
  42 file to add to <head>
  43 .TP
  44 --html-before-content <val>
  45 file to add in <body>, before content
  46 .TP
  47 --html-after-content <val>
  48 file to add in <body>, after content
  49 .TP
  50 -h, --help
  51 Print help
  52
  53 .SH "OUTPUT FORMATS"
  54
  55 The rustdoc tool can generate output in either an HTML or JSON format.
  56
  57 If using an HTML format, then the specified output destination will be the root
  58 directory of an HTML structure for all the documentation. Pages will be placed
  59 into this directory, and source files will also possibly be rendered into it as
  60 well.
  61
  62 If using a JSON format, then the specified output destination will have the
  63 rustdoc output serialized as JSON into it. This output format exists to
  64 pre-compile documentation for crates, and for usage in non-rustdoc tools. The
  65 JSON output is the following hash:
  66
  67     {
  68         "schema": VERSION,
  69         "crate": ...,
  70         "plugins": ...,
  71     }
  72
  73 The schema version indicates what the structure of crate/plugins will look
  74 like. Within a schema version the structure will remain the same. The `crate`
  75 field will contain all relevant documentation for the source being documented,
  76 and the `plugins` field will contain the output of the plugins run over the
  77 crate.
  78
  79 .SH "EXAMPLES"
  80
  81 To generate documentation for the source in the current directory:
  82     $ rustdoc hello.rs
  83
  84 List all available passes that rustdoc has, along with default passes:
  85     $ rustdoc --passes list
  86
  87 To precompile the documentation for a crate, and then use it to render html at
  88 a later date:
  89     $ rustdoc -w json hello.rs
  90     $ rustdoc doc.json
  91
  92 The generated HTML can be viewed with any standard web browser.
  93
  94 .SH "SEE ALSO"
  95
  96 rustc
  97
  98 .SH "BUGS"
  99 See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues.
 100
 101 .SH "AUTHOR"
 102 See \fBAUTHORS.txt\fR in the Rust source distribution.
 103
 104 .SH "COPYRIGHT"
 105 This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
 106 file in the rust source distribution.