mirror of https://github.com/rust-lang/rust.git
Usable instructions for generating docs from source
This commit is contained in:
parent
769c2e5f99
commit
fd24cb7eae
27
doc/README
27
doc/README
|
@ -1,10 +1,25 @@
|
||||||
The markdown docs are only generated by make when node is installed (use
|
Pandoc, a universal document converter, is required to generate docs as HTML
|
||||||
`make doc`). If you don't have node installed you can generate them yourself.
|
from Rust's source code. It's available for most platforms here:
|
||||||
Unfortunately there's no real standard for markdown and all the tools work
|
http://johnmacfarlane.net/pandoc/installing.html
|
||||||
differently. pandoc is one that seems to work well.
|
|
||||||
|
|
||||||
To generate an html version of a doc do something like:
|
Node.js (http://nodejs.org/) is also required for generating HTML from
|
||||||
pandoc --from=markdown --to=html --number-sections -o build/doc/rust.html doc/rust.md && git web--browse build/doc/rust.html
|
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:
|
The syntax for pandoc flavored markdown can be found at:
|
||||||
http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
|
http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
|
||||||
|
|
Loading…
Reference in New Issue