man/rustdoc.1

   1 .TH RUSTDOC "1" "March 2014" "rustdoc 0.13.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 --target <val>
  39 target triple to document
  40 .TP
  41 --crate-name <val>
  42 specify the name of this crate
  43 .TP
  44 -L --library-path <val>
  45 directory to add to crate search path
  46 .TP
  47 --cfg <val>
  48 pass a --cfg to rustc
  49 .TP
  50 --extern <val>
  51 pass an --extern to rustc
  52 .TP
  53 --test
  54 run code examples as tests
  55 .TP
  56 --test-args <val>
  57 pass arguments to the test runner
  58 .TP
  59 --html-in-header <val>
  60 file to add to <head>
  61 .TP
  62 --html-before-content <val>
  63 file to add in <body>, before content
  64 .TP
  65 --html-after-content <val>
  66 file to add in <body>, after content
  67 .TP
  68 --markdown-css <val>
  69 CSS files to include via <link> in a rendered Markdown file
  70 .TP
  71 --markdown-playground-url <val>
  72 URL to send code snippets to
  73 .TP
  74 --markdown-no-toc
  75 don't include table of contents
  76 .TP
  77 -h, --help
  78 Print help
  79 .TP
  80 -V, --version
  81 Print rustdoc's version
  82
  83 .SH "OUTPUT FORMATS"
  84
  85 The rustdoc tool can generate output in either an HTML or JSON format.
  86
  87 If using an HTML format, then the specified output destination will be the root
  88 directory of an HTML structure for all the documentation. Pages will be placed
  89 into this directory, and source files will also possibly be rendered into it as
  90 well.
  91
  92 If using a JSON format, then the specified output destination will have the
  93 rustdoc output serialized as JSON into it. This output format exists to
  94 pre-compile documentation for crates, and for usage in non-rustdoc tools. The
  95 JSON output is the following hash:
  96
  97     {
  98         "schema": VERSION,
  99         "crate": ...,
 100         "plugins": ...,
 101     }
 102
 103 The schema version indicates what the structure of crate/plugins will look
 104 like. Within a schema version the structure will remain the same. The `crate`
 105 field will contain all relevant documentation for the source being documented,
 106 and the `plugins` field will contain the output of the plugins run over the
 107 crate.
 108
 109 .SH "EXAMPLES"
 110
 111 To generate documentation for the source in the current directory:
 112     $ rustdoc hello.rs
 113
 114 List all available passes that rustdoc has, along with default passes:
 115     $ rustdoc --passes list
 116
 117 To precompile the documentation for a crate, and then use it to render html at
 118 a later date:
 119     $ rustdoc -w json hello.rs
 120     $ rustdoc doc.json
 121
 122 The generated HTML can be viewed with any standard web browser.
 123
 124 .SH "SEE ALSO"
 125
 126 rustc
 127
 128 .SH "BUGS"
 129 See <\fBhttps://github.com/rust-lang/rust/issues\fR> for issues.
 130
 131 .SH "AUTHOR"
 132 See \fBAUTHORS.txt\fR in the Rust source distribution.
 133
 134 .SH "COPYRIGHT"
 135 This work is dual-licensed under Apache 2.0 and MIT terms.  See \fBCOPYRIGHT\fR
 136 file in the rust source distribution.