d0f8cf32b3
set cfg(rustdoc) when rustdoc is running on a crate When using `#[doc(cfg)]` to document platform-specific items, it's a little cumbersome to get all the platforms' items to appear all at once. For example, the standard library adds `--cfg dox` to rustdoc's command line whenever it builds docs, and the documentation for `#![feature(doc_cfg)]` suggests using a Cargo feature to approximate the same thing. This is a little awkward, because you always need to remember to set `--features dox` whenever you build documentation. This PR proposes making rustdoc set `#[cfg(rustdoc)]` whenever it runs on a crate, to provide an officially-sanctioned version of this that is set automatically. This way, there's a standardized way to declare that a certain version of an item is specifically when building docs. To try to prevent the spread of this feature from happening too quickly, this PR also restricts the use of this flag to whenever `#![feature(doc_cfg)]` is active. I'm sure there are other uses for this, but right now i'm tying it to this feature. (If it makes more sense to give this its own feature, i can easily do that.) |
||
|---|---|---|
| .. | ||
| book@16c9dee766 | ||
| man | ||
| nomicon@ae42ad7aa4 | ||
| reference@219e261ddb | ||
| rust-by-example@e3719fc78f | ||
| rustc | ||
| rustdoc | ||
| unstable-book | ||
| complement-design-faq.md | ||
| complement-lang-faq.md | ||
| complement-project-faq.md | ||
| favicon.inc | ||
| footer.inc | ||
| full-toc.inc | ||
| grammar.md | ||
| guide-crates.md | ||
| guide-error-handling.md | ||
| guide-ffi.md | ||
| guide-macros.md | ||
| guide-ownership.md | ||
| guide-plugins.md | ||
| guide-pointers.md | ||
| guide-strings.md | ||
| guide-tasks.md | ||
| guide-testing.md | ||
| guide-unsafe.md | ||
| guide.md | ||
| index.md | ||
| intro.md | ||
| not_found.md | ||
| README.md | ||
| reference.md | ||
| rust.css | ||
| rust.md | ||
| rustc-ux-guidelines.md | ||
| rustdoc.md | ||
| tutorial.md | ||
| version_info.html.template | ||
Rust documentations
Building
To generate all the docs, follow the "Building Documentation" instructions in the README in the root of the repository. This will convert the distributed Markdown docs to HTML and generate HTML doc for the books, 'std' and 'extra' libraries.
To generate HTML documentation from one source file/crate, do something like:
rustdoc --output html-doc/ --output-format html ../src/libstd/path.rs
(This, of course, requires a working build of the rustdoc tool.)
Additional notes
To generate an HTML version of a doc from Markdown manually, you can do something like:
rustdoc reference.md
(reference.md being the Rust Reference Manual.)
An overview of how to use the rustdoc command is available in the docs.
Further details are available from the command line by with rustdoc --help.