src/doc/rustdoc/src/what-is-rustdoc.md

   1 # What is rustdoc?
   2
   3 The standard Rust distribution ships with a tool called `rustdoc`. Its job is
   4 to generate documentation for Rust projects. On a fundamental level, Rustdoc
   5 takes as an argument either a crate root or a Markdown file, and produces HTML,
   6 CSS, and JavaScript.
   7
   8 ## Basic usage
   9
  10 Let's give it a try! Let's create a new project with Cargo:
  11
  12 ```bash
  13 $ cargo new docs
  14 $ cd docs
  15 ```
  16
  17 In `src/lib.rs`, you'll find that Cargo has generated some sample code. Delete
  18 it and replace it with this:
  19
  20 ```rust
  21 /// foo is a function
  22 fn foo() {}
  23 ```
  24
  25 Let's run `rustdoc` on our code. To do so, we can call it with the path to
  26 our crate root like this:
  27
  28 ```bash
  29 $ rustdoc src/lib.rs
  30 ```
  31
  32 This will create a new directory, `doc`, with a website inside! In our case,
  33 the main page is located in `doc/lib/index.html`. If you open that up in
  34 a web browser, you'll see a page with a search bar, and "Crate lib" at the
  35 top, with no contents. There's two problems with this: first, why does it
  36 think that our package is named "lib"? Second, why does it not have any
  37 contents?
  38
  39 The first problem is due to `rustdoc` trying to be helpful; like `rustc`,
  40 it assumes that our crate's name is the name of the file for the crate
  41 root. To fix this, we can pass in a command-line flag:
  42
  43 ```bash
  44 $ rustdoc src/lib.rs --crate-name docs
  45 ```
  46
  47 Now, `doc/docs/index.html` will be generated, and the page says "Crate docs."
  48
  49 For the second issue, it's because our function `foo` is not public; `rustdoc`
  50 defaults to generating documentation for only public functions. If we change
  51 our code...
  52
  53 ```rust
  54 /// foo is a function
  55 pub fn foo() {}
  56 ```
  57
  58 ... and then re-run `rustdoc`:
  59
  60 ```bash
  61 $ rustdoc src/lib.rs --crate-name docs
  62 ```
  63
  64 We'll have some generated documentation. Open up `doc/docs/index.html` and
  65 check it out! It should show a link to the `foo` function's page, which
  66 is located at `doc/docs/fn.foo.html`. On that page, you'll see the "foo is
  67 a function" we put inside the documentation comment in our crate.
  68
  69 ## Using rustdoc with Cargo
  70
  71 Cargo also has integration with `rustdoc` to make it easier to generate
  72 docs. Instead of the `rustdoc` command, we could have done this:
  73
  74 ```bash
  75 $ cargo doc
  76 ```
  77
  78 Internally, this calls out to `rustdoc` like this:
  79
  80 ```bash
  81 $ rustdoc --crate-name docs srclib.rs -o <path>\docs\target\doc -L
  82 dependency=<path>docs\target\debug\deps
  83 ```
  84
  85 You can see this with `cargo doc --verbose`.
  86
  87 It generates the correct `--crate-name` for us, as well as pointing to
  88 `src/lib.rs` But what about those other arguments? `-o` controls the
  89 *o*utput of our docs. Instead of a top-level `doc` directory, you'll
  90 notice that Cargo puts generated documentation under `target`. That's
  91 the idiomatic place for generated files in Cargo projects. Also, it
  92 passes `-L`, a flag that helps rustdoc find the dependencies
  93 your code relies on. If our project used dependencies, we'd get
  94 documentation for them as well!
  95
  96 ## Using standalone Markdown files
  97
  98 `rustdoc` can also generate HTML from standalone Markdown files. Let's
  99 give it a try: create a `README.md` file with these contents:
 100
 101 ````text
 102 # Docs
 103
 104 This is a project to test out `rustdoc`.
 105
 106 [Here is a link!](https://www.rust-lang.org)
 107
 108 ## Subheading
 109
 110 ```rust
 111 fn foo() -> i32 {
 112     1 + 1
 113 }
 114 ```
 115 ````
 116
 117 And call `rustdoc` on it:
 118
 119 ```bash
 120 $ rustdoc README.md
 121 ```
 122
 123 You'll find an HTML file in `docs/doc/README.html` generated from its
 124 Markdown contents.
 125
 126 Cargo currently does not understand standalone Markdown files, unfortunately.
 127
 128 ## Summary
 129
 130 This covers the simplest use-cases of `rustdoc`. The rest of this book will
 131 explain all of the options that `rustdoc` has, and how to use them.