Usable instructions for generating docs from source

1 files changed, 21 insertions, 6 deletions

diff --git a/doc/README b/doc/README
index c3bb28a9e85..bb6ab77a802 100644
--- a/doc/README
+++ b/doc/README
@@ -1,10 +1,25 @@
-The markdown docs are only generated by make when node is installed (use
-`make doc`). If you don't have node installed you can generate them yourself.
-Unfortunately there's no real standard for markdown and all the tools work
-differently. pandoc is one that seems to work well.
+Pandoc, a universal document converter, is required to generate docs as HTML
+from Rust's source code. It's available for most platforms here:
+http://johnmacfarlane.net/pandoc/installing.html
 
-To generate an html version of a doc do something like:
-pandoc --from=markdown --to=html --number-sections -o build/doc/rust.html doc/rust.md && git web--browse build/doc/rust.html
+Node.js (http://nodejs.org/) is also required for generating HTML from
+the Markdown docs (reference manual, tutorials, etc.) distributed with
+this git repository.
+
+To generate all the docs, run `make docs` from the root of the repository.
+This will convert the distributed Markdown docs to HTML and generate HTML doc
+for the 'std' and 'extra' libraries.
+
+To generate HTML documentation from one source file/crate, do something like:
+
+  rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs
+
+(This, of course, requires that you've built/installed the `rustdoc` tool.)
+
+To generate an HTML version of a doc from Markdown, without having Node.js
+installed, do something like:
+
+  pandoc --from=markdown --to=html --number-sections -o rust.html rust.md
 
 The syntax for pandoc flavored markdown can be found at:
 http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown