Auto merge of #42378 - steveklabnik:rustdoc-docs, r=frewsxcv

The Rustdoc book

A work-in-progress start for docs for rustdoc.

This doesn't actually generate the docs yet; I wanted to open this PR to get feedback on this approach, the chapters headings themselves, and to see if anyone wanted to help fill in the ones that aren't done yet.

Start of #42322.

/cc @rust-lang/dev-tools @rust-lang/docs

src/doc/rustdoc/.gitignore

@@ -0,0 +1 @@
+book

src/doc/rustdoc/src/SUMMARY.md

@@ -0,0 +1,8 @@
+# The Rustdoc Book
+
+- [What is rustdoc?](what-is-rustdoc.md)
+- [Command-line arguments](command-line-arguments.md)
+- [In-source directives](in-source-directives.md)
+- [Documentation tests](documentation-tests.md)
+- [Plugins](plugins.md)
+- [Passes](passes.md)

src/doc/rustdoc/src/command-line-arguments.md

@@ -0,0 +1,348 @@
+# Command-line arguments
+
+Here's the list of arguments you can pass to `rustdoc`:
+
+## `-h`/`--help`: help
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc -h
+$ rustdoc --help
+```
+
+This will show `rustdoc`'s built-in help, which largely consists of
+a list of possible command-line flags.
+
+Some of `rustdoc`'s flags are unstable; this page only shows stable
+options, `--help` will show them all.
+
+## `-V`/`--version`: version information
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc -V
+$ rustdoc --version
+```
+
+This will show `rustdoc`'s version, which will look something
+like this:
+
+```text
+rustdoc 1.17.0 (56124baa9 2017-04-24)
+```
+
+## `-v`/`--verbose`: more verbose output
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc -v src/lib.rs
+$ rustdoc --verbose src/lib.rs
+```
+
+This enables "verbose mode", which means that more information will be written
+to standard out. What is written depends on the other flags you've passed in.
+For example, with `--version`:
+
+```text
+$ rustdoc --verbose --version
+rustdoc 1.17.0 (56124baa9 2017-04-24)
+binary: rustdoc
+commit-hash: hash
+commit-date: date
+host: host-triple
+release: 1.17.0
+LLVM version: 3.9
+```
+
+## `-r`/`--input-format`: input format
+
+This flag is currently ignored; the idea is that `rustdoc` would support various
+input formats, and you could specify them via this flag.
+
+Rustdoc only supports Rust source code and Markdown input formats. If the
+file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
+Otherwise, it assumes that the input file is Rust.
+
+
+## `-w`/`--output-format`: output format
+
+This flag is currently ignored; the idea is that `rustdoc` would support
+various output formats, and you could specify them via this flag.
+
+Rustdoc only supports HTML output, and so this flag is redundant today.
+
+## `-o`/`--output`: output path
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -o target\\doc
+$ rustdoc src/lib.rs --output target\\doc
+```
+
+By default, `rustdoc`'s output appears in a directory named `doc` in
+the current working directory. With this flag, it will place all output
+into the directory you specify.
+
+
+## `--crate-name`: controlling the name of the crate
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --crate-name mycrate
+```
+
+By default, `rustodc` assumes that the name of your crate is the same name
+as the `.rs` file. `--crate-name` lets you override this assumption with
+whatever name you choose.
+
+## `-L`/`--library-path`: 
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -L target/debug/deps
+$ rustdoc src/lib.rs --library-path target/debug/deps
+```
+
+If your crate has dependencies, `rustdoc` needs to know where to find them.
+Passing `--library-path` gives `rustdoc` a list of places to look for these
+dependencies.
+
+This flag takes any number of directories as its argument, and will use all of
+them when searching.
+
+
+## `--cfg`: passing configuration flags
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --cfg feature="foo"
+```
+
+This flag accepts the same values as `rustc --cfg`, and uses it to configure
+compilation. The example above uses `feature`, but any of the `cfg` values
+are acceptable.
+
+## `--extern`: specify a dependency's location
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --extern lazy-static=/path/to/lazy-static
+```
+
+Similar to `--library-path`, `--extern` is about specifying the location
+of a dependency. `--library-path` provides directories to search in, `--extern`
+instead lets you specify exactly which dependency is located where.
+
+
+## `--plugin-path`: loading plugins
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --plugin-path=/path/to/plugins
+```
+
+Similar to `--library-path`, but for plugins. For more, see
+the [chapter on plugins](plugins.html).
+
+See also: `--plugins`.
+
+## `--passes`: add more rustdoc passes
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc --passes list
+$ rustdoc src/lib.rs --passes strip-priv-imports
+```
+
+An argument of "list" will print a list of possible "rustdoc passes", and other
+arguments will be the name of which passes to run in addition to the defaults.
+
+For more details on passes, see [the chapter on them](passes.html).
+
+See also `--no-defaults`.
+
+## `--plugins`: 
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --plugins foo bar
+```
+
+For more, see the [chapter on plugins](plugins.html).
+
+See also: `--plugin-path`.
+
+## `--no-defaults`: don't run default passes
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --no-defaults
+```
+
+By default, `rustdoc` will run several passes over your code. This
+removes those defaults, allowing you to use `--passes` to specify
+exactly which passes you want.
+
+For more details on passes, see [the chapter on them](passes.html).
+
+See also `--passes`.
+
+## `--test`: run code examples as tests
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --test
+```
+
+This flag will run your code examples as tests. For more, see [the chapter
+on documentation tests](documentation-tests.html).
+
+See also `--test-args`.
+
+## `--test-args`: 
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --test --test-args ignored
+```
+
+This flag will pass options to the test runner when running documentation tests.
+For more, see [the chapter on documentation tests](documentation-tests.html).
+
+See also `--test`.
+
+## `--target`: 
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --target x86_64-pc-windows-gnu
+```
+
+Similar to the `--target` flag for `rustc`, this generates documentation
+for a target triple that's different than your host triple.
+
+All of the usual caveats of cross-compiling code apply.
+
+## `--markdown-css`: include more CSS files when rendering markdown
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc README.md --markdown-css foo.css
+```
+
+When rendering Markdown files, this will create a `<link>` element in the
+`<head>` section of the generated HTML. For example, with the invocation above,
+
+```html
+<link rel="stylesheet" type="text/css" href="foo.css">
+```
+
+will be added.
+
+When rendering Rust files, this flag is ignored.
+
+## `--html-in-header`: include more HTML in <head>
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --html-in-header header.html
+$ rustdoc README.md --html-in-header header.html
+```
+
+This flag takes a list of files, and inserts them into the `<head>` section of
+the rendered documentation.
+
+## `--html-before-content`: include more HTML before the content
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --html-before-content extra.html
+$ rustdoc README.md --html-before-content extra.html
+```
+
+This flag takes a list of files, and inserts them inside the `<body>` tag but
+before the other content `rustodc` would normally produce in the rendered
+documentation.
+
+## `--html-after-content`: include more HTML after the content
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --html-after-content extra.html
+$ rustdoc README.md --html-after-content extra.html
+```
+
+This flag takes a list of files, and inserts them before the `</body>` tag but
+after the other content `rustodc` would normally produce in the rendered
+documentation.
+
+
+## `--markdown-playground-url`: control the location of the playground
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc README.md --markdown-playground-url https://play.rust-lang.org/
+```
+
+When rendering a Markdown file, this flag gives the base URL of the Rust
+Playround, to use for generating `Run` buttons.
+
+
+## `--markdown-no-toc`: don't generate a table of contents
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc README.md --markdown-no-toc
+```
+
+When generating documentation from a Markdown file, by default, `rustdoc` will
+generate a table of contents. This flag supresses that, and no TOC will be
+generated.
+
+
+## `-e`/`--extend-css`: extend rustdoc's CSS
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs -e extra.css
+$ rustdoc src/lib.rs --extend-css extra.css
+```
+
+With this flag, the contents of the files you pass are included at the bottom
+of Rustdoc's `theme.css` file.
+
+While this flag is stable, the contents of `theme.css` are not, so be careful!
+Updates may break your theme extensions.
+
+## `--sysroot`: override the system root
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc src/lib.rs --sysroot /path/to/sysroot
+```
+
+Similar to `rustc --sysroot`, this lets you change the sysroot `rustdoc` uses
+when compiling your code.

src/doc/rustdoc/src/documentation-tests.md

@@ -0,0 +1,3 @@
+# Documentation tests
+
+Coming soon!

src/doc/rustdoc/src/in-source-directives.md

@@ -0,0 +1,3 @@
+# In-source directives
+
+Coming soon!

src/doc/rustdoc/src/passes.md

@@ -0,0 +1,3 @@
+# Passes
+
+Coming soon!

src/doc/rustdoc/src/plugins.md

@@ -0,0 +1,3 @@
+# Plugins
+
+Coming soon!

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

@@ -0,0 +1,131 @@
+# What is rustdoc?
+
+The standard Rust distribution ships with a tool called `rustdoc`. Its job is
+to generate documentation for Rust projects. On a fundamental level, Rustdoc
+takes as an argument either a crate root or a Markdown file, and produces HTML,
+CSS, and JavaScript.
+
+## Basic usage
+
+Let's give it a try! Let's create a new project with Cargo:
+
+```bash
+$ cargo new docs
+$ cd docs
+```
+
+In `src/lib.rs`, you'll find that Cargo has generated some sample code. Delete
+it and replace it with this:
+
+```rust
+/// foo is a function
+fn foo() {}
+```
+
+Let's run `rustdoc` on our code. To do so, we can call it with the path to
+our crate root like this:
+
+```bash
+$ rustdoc src/lib.rs
+```
+
+This will create a new directory, `doc`, with a website inside! In our case,
+the main page is located in `doc/lib/index.html`. If you open that up in
+a web browser, you'll see a page with a search bar, and "Crate lib" at the
+top, with no contents. There's two problems with this: first, why does it
+think that our package is named "lib"? Second, why does it not have any
+contents?
+
+The first problem is due to `rustdoc` trying to be helpful; like `rustc`,
+it assumes that our crate's name is the name of the file for the crate
+root. To fix this, we can pass in a command-line flag:
+
+```bash
+$ rustdoc src/lib.rs --crate-name docs
+```
+
+Now, `doc/docs/index.html` will be generated, and the page says "Crate docs."
+
+For the second issue, it's because our function `foo` is not public; `rustdoc`
+defaults to generating documentation for only public functions. If we change
+our code...
+
+```rust
+/// foo is a function
+pub fn foo() {}
+```
+
+... and then re-run `rustdoc`:
+
+```bash
+$ rustdoc src/lib.rs --crate-name docs
+```
+
+We'll have some generated documentation. Open up `doc/docs/index.html` and
+check it out! It should show a link to the `foo` function's page, which
+is located at `doc/docs/fn.foo.html`. On that page, you'll see the "foo is
+a function" we put inside the documentation comment in our crate.
+
+## Using rustdoc with Cargo
+
+Cargo also has integration with `rustdoc` to make it easier to generate
+docs. Instead of the `rustdoc` command, we could have done this:
+
+```bash
+$ cargo doc
+```
+
+Internally, this calls out to `rustdoc` like this:
+
+```bash
+$ rustdoc --crate-name docs srclib.rs -o <path>\docs\target\doc -L
+dependency=<path>docs\target\debug\deps
+```
+
+You can see this with `cargo doc --verbose`.
+
+It generates the correct `--crate-name` for us, as well as pointing to
+`src/lib.rs` But what about those other arguments? `-o` controls the
+*o*utput of our docs. Instead of a top-level `doc` directory, you'll
+notice that Cargo puts generated documentation under `target`. That's
+the idiomatic place for generated files in Cargo projects. Also, it
+passes `-L`, a flag that helps rustdoc find the dependencies
+your code relies on. If our project used dependencies, we'd get
+documentation for them as well!
+
+## Using standalone Markdown files
+
+`rustdoc` can also generate HTML from standalone Markdown files. Let's
+give it a try: create a `README.md` file with these contents:
+
+```text
+    # Docs
+
+    This is a project to test out `rustdoc`.
+
+    [Here is a link!](https://www.rust-lang.org)
+
+    ## Subheading
+
+    ```rust
+    fn foo() -> i32 {
+        1 + 1
+    }
+    ```
+```
+
+And call `rustdoc` on it:
+
+```bash
+$ rustdoc README.md
+```
+
+You'll find an HTML file in `docs/doc/README.html` generated from its
+Markdown contents.
+
+Cargo currently does not understand standalone Markdown files, unfortunately.
+
+## Summary
+
+This covers the simplest use-cases of `rustdoc`. The rest of this book will
+explain all of the options that `rustdoc` has, and how to use them.