man/rustdoc.1

   1 .TH RUSTDOC "1" "August 2015" "rustdoc 1.2.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 .UR https://www.rust\-lang.org
  12 .UE .
  13 It accepts several input formats and provides several output formats
  14 for the generated documentation.
  15
  16 .SH OPTIONS
  17
  18 .TP
  19 \fB\-r\fR, \fB\-\-input\-format\fR \fIFORMAT\fR
  20 html or json (default: inferred)
  21 .TP
  22 \fB\-w\fR, \fB\-\-output\-format\fR \fIFORMAT\fR
  23 html or json (default: html)
  24 .TP
  25 \fB\-o\fR, \fB\-\-output\fR \fIOUTPUT\fR
  26 where to place the output (default: \fIdoc/\fR for html,
  27 \fIdoc.json\fR for json)
  28 .TP
  29 \fB\-\-passes\fR \fILIST\fR
  30 space\[hy]separated list of passes to run (default: '')
  31 .TP
  32 \fB\-\-no\-defaults\fR
  33 don't run the default passes
  34 .TP
  35 \fB\-\-plugins\fR \fILIST\fR
  36 space-separated list of plugins to run (default: '')
  37 .TP
  38 \fB\-\-plugin\-path\fR \fIDIR\fR
  39 directory to load plugins from (default: \fI/tmp/rustdoc_ng/plugins\fR)
  40 .TP
  41 \fB\-\-target\fR \fITRIPLE\fR
  42 target triple to document
  43 .TP
  44 \fB\-\-crate\-name\fR \fINAME\fR
  45 specify the name of this crate
  46 .TP
  47 \fB\-L\fR, \fB\-\-library\-path\fR \fIDIR\fR
  48 directory to add to crate search path
  49 .TP
  50 \fB\-\-cfg\fR \fISPEC\fR
  51 pass a \fI\-\-cfg\fR to rustc
  52 .TP
  53 \fB\-\-extern\fR \fIVAL\fR
  54 pass an \fI\-\-extern\fR to rustc
  55 .TP
  56 \fB\-\-test\fR
  57 run code examples as tests
  58 .TP
  59 \fB\-\-test\-args\fR \fIARGS\fR
  60 pass arguments to the test runner
  61 .TP
  62 \fB\-\-html\-in\-header\fR \fIFILE\fR
  63 file to add to <head>
  64 .TP
  65 \fB\-\-html\-before\-content\fR \fIFILE\fR
  66 file to add in <body>, before content
  67 .TP
  68 \fB\-\-html\-after\-content\fR \fIFILE\fR
  69 file to add in <body>, after content
  70 .TP
  71 \fB\-\-markdown\-css\fR \fIFILE\fR
  72 CSS files to include via <link> in a rendered Markdown file
  73 .TP
  74 \fB\-\-markdown\-playground\-url\fR \fIURL\fR
  75 URL to send code snippets to
  76 .TP
  77 \fB\-\-markdown\-no\-toc\fR
  78 don't include table of contents
  79 .TP
  80 \fB\-h\fR, \fB\-\-help\fR
  81 Print help
  82 .TP
  83 \fB\-V\fR, \fB\-\-version\fR
  84 Print rustdoc's version
  85
  86 .SH "OUTPUT FORMATS"
  87
  88 The rustdoc tool can generate output in either an HTML or JSON format.
  89
  90 If using an HTML format, then the specified output destination will be the root
  91 directory of an HTML structure for all the documentation.
  92 Pages will be placed into this directory, and source files will also
  93 possibly be rendered into it as well.
  94
  95 If using a JSON format, then the specified output destination will have the
  96 rustdoc output serialized as JSON into it.
  97 This output format exists to pre\[hy]compile documentation for crates,
  98 and for usage in non\[hy]rustdoc tools.
  99 The JSON output is the following hash:
 100
 101     {
 102         "schema": VERSION,
 103         "crate": ...,
 104         "plugins": ...,
 105     }
 106
 107 The schema version indicates what the structure of crate/plugins will
 108 look like.
 109 Within a schema version the structure will remain the same.
 110 The \fIcrate\fR field will contain all relevant documentation for the
 111 source being documented, and the \fIplugins\fR field will contain the
 112 output of the plugins run over the crate.
 113
 114 .SH "EXAMPLES"
 115
 116 To generate documentation for the source in the current directory:
 117     $ rustdoc hello.rs
 118
 119 List all available passes that rustdoc has, along with default passes:
 120     $ rustdoc \-\-passes list
 121
 122 To precompile the documentation for a crate, and then use it to render html at
 123 a later date:
 124     $ rustdoc \-w json hello.rs
 125     $ rustdoc doc.json
 126
 127 The generated HTML can be viewed with any standard web browser.
 128
 129 .SH "SEE ALSO"
 130
 131 .BR rustc (1)
 132
 133 .SH "BUGS"
 134 See
 135 .UR https://github.com/rust\-lang/rust/issues
 136 .UE
 137 for issues.
 138
 139 .SH "AUTHOR"
 140 See \fIAUTHORS.txt\fR in the Rust source distribution.
 141
 142 .SH "COPYRIGHT"
 143 This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
 144 See \fICOPYRIGHT\fR file in the rust source distribution.