From 4ed3a15bfc3a4dafe4a9fe17cbfdf178e7d6ed4d Mon Sep 17 00:00:00 2001
From: steveklabnik <steve@steveklabnik.com>
Date: Thu, 1 Jun 2017 10:56:06 -0400
Subject: [PATCH] wip

---
 src/doc/rustdoc/src/SUMMARY.md                |   9 +-
 src/doc/rustdoc/src/chapter_1.md              |   1 -
 src/doc/rustdoc/src/command-line-arguments.md | 358 ++++++++++++++++++
 src/doc/rustdoc/src/documentation-tests.md    |   1 +
 src/doc/rustdoc/src/in-source-directives.md   |   1 +
 src/doc/rustdoc/src/what-is-rustdoc.md        | 127 +++++++
 6 files changed, 494 insertions(+), 3 deletions(-)
 delete mode 100644 src/doc/rustdoc/src/chapter_1.md
 create mode 100644 src/doc/rustdoc/src/command-line-arguments.md
 create mode 100644 src/doc/rustdoc/src/documentation-tests.md
 create mode 100644 src/doc/rustdoc/src/in-source-directives.md
 create mode 100644 src/doc/rustdoc/src/what-is-rustdoc.md

diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md
index 7390c82896e..cd6883a719c 100644
--- a/src/doc/rustdoc/src/SUMMARY.md
+++ b/src/doc/rustdoc/src/SUMMARY.md
@@ -1,3 +1,8 @@
-# Summary
+# The Rustdoc Book
 
-- [Chapter 1](./chapter_1.md)
+- [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)
\ No newline at end of file
diff --git a/src/doc/rustdoc/src/chapter_1.md b/src/doc/rustdoc/src/chapter_1.md
deleted file mode 100644
index b743fda3546..00000000000
--- a/src/doc/rustdoc/src/chapter_1.md
+++ /dev/null
@@ -1 +0,0 @@
-# Chapter 1
diff --git a/src/doc/rustdoc/src/command-line-arguments.md b/src/doc/rustdoc/src/command-line-arguments.md
new file mode 100644
index 00000000000..c8a86f1378f
--- /dev/null
+++ b/src/doc/rustdoc/src/command-line-arguments.md
@@ -0,0 +1,358 @@
+# 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.y.0 (hash date)
+```
+
+## `-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 --version -v
+rustdoc 1.y.0 (hash date)
+binary: rustdoc
+commit-hash: hash
+commit-date: date
+host: host-triple
+release: 1.y.0
+LLVM version: x.y
+```
+
+stable(optopt("r", "input-format", "the input type of the specified file",
+                "[rust]")),
+## `-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.
+
+
+stable(optopt("w", "output-format", "the output type to write",
+                "[html]")),
+## `-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.
+
+
+stable(optopt("", "crate-name", "specify the name of this crate", "NAME")),
+## `--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.
+
+stable(optmulti("L", "library-path", "directory to add to crate search path",
+                "DIR")),
+## `-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`.
+
+stable(optmulti("", "test-args", "arguments to pass to the test runner",
+                "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`.
+
+stable(optopt("", "target", "target triple to document", "TRIPLE")),
+## `--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.
\ No newline at end of file
diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md
new file mode 100644
index 00000000000..f60d75e2df8
--- /dev/null
+++ b/src/doc/rustdoc/src/documentation-tests.md
@@ -0,0 +1 @@
+# Documentation tests
diff --git a/src/doc/rustdoc/src/in-source-directives.md b/src/doc/rustdoc/src/in-source-directives.md
new file mode 100644
index 00000000000..93e619ebda0
--- /dev/null
+++ b/src/doc/rustdoc/src/in-source-directives.md
@@ -0,0 +1 @@
+# In-source directives
diff --git a/src/doc/rustdoc/src/what-is-rustdoc.md b/src/doc/rustdoc/src/what-is-rustdoc.md
new file mode 100644
index 00000000000..1cffbd51b4a
--- /dev/null
+++ b/src/doc/rustdoc/src/what-is-rustdoc.md
@@ -0,0 +1,127 @@
+# What is rustdoc?
+
+The standard Rust distribution ships with a tool called `rustdoc`. It's 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 -- lib
+$ 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
+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
+```
+
+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:
+
+    # 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.
\ No newline at end of file