Auto merge of #42612 - est31:master, r=nagisa

Autogenerate stubs and SUMMARY.md in the unstable book

Removes a speed bump in compiler development by autogenerating stubs for features in the unstable book. See #42454 for discussion.

The PR contains three commits, separated in order to make review easy:

* The first commit converts the tidy tool from a binary crate to a crate that contains both a library and a binary. In the second commit, we'll use the tidy library
* The second and main commit introduces autogeneration of SUMMARY.md and feature stub files
* The third commit turns off the tidy lint that checks for features without a stub, and removes the stub files. A separate commit due to the large number of files touched

Members of the doc team who wish to document some features can either do this (where `$rustsrc` is the root of the rust repo git checkout):

1. cd to `$rustsrc/src/tools/unstable-book-gen` and then do `cargo run $rustsrc/src $rustsrc/src/doc/unstable-book` to put the stubs into the unstable book
2. cd to `$rustsrc` and run `git ls-files --others --exclude-standard` to list the newly added stubs
3. choose a file to edit, then `git add` it and `git commit`
4. afterwards, remove all changes by the tool by doing `git --reset hard` and `git clean -f`

Or they can do this:

1. remove the comment marker in `src/tools/tidy/src/unstable_book.rs` line 122
2. run `./x.py test src/tools/tidy` to list the unstable features which only have stubs
3. revert the change in 1
3. document one of the chosen unstable features

The changes done by this PR also allow for further development:

* tidy obtains information about tracking issues. We can now forbid differing tracking issues between differing `#![unstable]` annotations. I haven't done this but plan to in a future PR
* we now have a general framework for generating stuff for the unstable book at build time. Further changes can autogenerate a list of the API a given library feature exposes.

The old way to simply click through the documentation after it has been uploaded to rust-lang.org works as well.

r? @nagisa

Fixes #42454
This commit is contained in:
bors 2017-06-16 14:41:15 +00:00
commit b40be00a0c
159 changed files with 421 additions and 1264 deletions

7
src/Cargo.lock generated
View File

@ -1892,6 +1892,13 @@ dependencies = [
"void 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)",
]
[[package]]
name = "unstable-book-gen"
version = "0.1.0"
dependencies = [
"tidy 0.1.0",
]
[[package]]
name = "url"
version = "1.4.0"

View File

@ -9,6 +9,7 @@ members = [
"tools/error_index_generator",
"tools/linkchecker",
"tools/rustbook",
"tools/unstable-book-gen",
"tools/tidy",
"tools/build-manifest",
"tools/remote-test-client",

View File

@ -27,18 +27,26 @@ use {Build, Compiler, Mode};
use util::{cp_r, symlink_dir};
use build_helper::up_to_date;
/// Invoke `rustbook` as compiled in `stage` for `target` for the doc book
/// `name` into the `out` path.
/// Invoke `rustbook` for `target` for the doc book `name`.
///
/// This will not actually generate any documentation if the documentation has
/// already been generated.
pub fn rustbook(build: &Build, target: &str, name: &str) {
let src = build.src.join("src/doc");
rustbook_src(build, target, name, &src);
}
/// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
///
/// This will not actually generate any documentation if the documentation has
/// already been generated.
pub fn rustbook_src(build: &Build, target: &str, name: &str, src: &Path) {
let out = build.doc_out(target);
t!(fs::create_dir_all(&out));
let out = out.join(name);
let compiler = Compiler::new(0, &build.config.build);
let src = build.src.join("src/doc").join(name);
let src = src.join(name);
let index = out.join("index.html");
let rustbook = build.tool(&compiler, "rustbook");
if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
@ -354,6 +362,19 @@ pub fn error_index(build: &Build, target: &str) {
build.run(&mut index);
}
pub fn unstable_book_gen(build: &Build, target: &str) {
println!("Generating unstable book md files ({})", target);
let out = build.md_doc_out(target).join("unstable-book");
t!(fs::create_dir_all(&out));
t!(fs::remove_dir_all(&out));
let compiler = Compiler::new(0, &build.config.build);
let mut cmd = build.tool_cmd(&compiler, "unstable-book-gen");
cmd.arg(build.src.join("src"));
cmd.arg(out);
build.run(&mut cmd);
}
fn symlink_dir_force(src: &Path, dst: &Path) -> io::Result<()> {
if let Ok(m) = fs::symlink_metadata(dst) {
if m.file_type().is_dir() {

View File

@ -680,6 +680,11 @@ impl Build {
self.out.join(target).join("doc")
}
/// Output directory for some generated md crate documentation for a target (temporary)
fn md_doc_out(&self, target: &str) -> PathBuf {
self.out.join(target).join("md-doc")
}
/// Output directory for all crate documentation for a target (temporary)
///
/// The artifacts here are then copied into `doc_out` above.

View File

@ -548,6 +548,10 @@ pub fn build_rules<'a>(build: &'a Build) -> Rules {
.dep(|s| s.name("maybe-clean-tools"))
.dep(|s| s.name("librustc-tool"))
.run(move |s| compile::tool(build, s.stage, s.target, "error_index_generator"));
rules.build("tool-unstable-book-gen", "src/tools/unstable-book-gen")
.dep(|s| s.name("maybe-clean-tools"))
.dep(|s| s.name("libstd-tool"))
.run(move |s| compile::tool(build, s.stage, s.target, "unstable-book-gen"));
rules.build("tool-tidy", "src/tools/tidy")
.dep(|s| s.name("maybe-clean-tools"))
.dep(|s| s.name("libstd-tool"))
@ -662,8 +666,12 @@ pub fn build_rules<'a>(build: &'a Build) -> Rules {
.target(&build.config.build)
.stage(0)
})
.dep(move |s| s.name("doc-unstable-book-gen"))
.default(build.config.docs)
.run(move |s| doc::rustbook(build, s.target, "unstable-book"));
.run(move |s| doc::rustbook_src(build,
s.target,
"unstable-book",
&build.md_doc_out(s.target)));
rules.doc("doc-standalone", "src/doc")
.dep(move |s| {
s.name("rustc")
@ -679,6 +687,17 @@ pub fn build_rules<'a>(build: &'a Build) -> Rules {
.default(build.config.docs)
.host(true)
.run(move |s| doc::error_index(build, s.target));
rules.doc("doc-unstable-book-gen", "src/tools/unstable-book-gen")
.dep(move |s| {
s.name("tool-unstable-book-gen")
.host(&build.config.build)
.target(&build.config.build)
.stage(0)
})
.dep(move |s| s.name("libstd-link"))
.default(build.config.docs)
.host(true)
.run(move |s| doc::unstable_book_gen(build, s.target));
for (krate, path, default) in krates("std") {
rules.doc(&krate.doc_step, path)
.dep(|s| s.name("libstd-link"))

View File

@ -1,7 +0,0 @@
# `abi_sysv64`
The tracking issue for this feature is: [#36167]
[#36167]: https://github.com/rust-lang/rust/issues/36167
------------------------

View File

@ -1,6 +0,0 @@
# `abi_unadjusted`
The tracking issue for this feature is: none.
------------------------

View File

@ -1,7 +0,0 @@
# `abi_vectorcall`
The tracking issue for this feature is: none.
------------------------

View File

@ -1,7 +0,0 @@
# `abi_x86_interrupt`
The tracking issue for this feature is: [#40180]
[#40180]: https://github.com/rust-lang/rust/issues/40180
------------------------

View File

@ -1,6 +0,0 @@
# `allow_internal_unstable`
The tracking issue for this feature is: None.
------------------------

View File

@ -190,4 +190,4 @@ constraints, etc.
[llvm-docs]: http://llvm.org/docs/LangRef.html#inline-assembler-expressions
If you need more power and don't mind losing some of the niceties of
`asm!`, check out [global_asm](language-features/global_asm.html).
`asm!`, check out [global_asm](language-features/global-asm.html).

View File

@ -1,10 +0,0 @@
# `associated_type_defaults`
The tracking issue for this feature is: [#29661]
[#29661]: https://github.com/rust-lang/rust/issues/29661
------------------------

View File

@ -1,10 +0,0 @@
# `cfg_target_feature`
The tracking issue for this feature is: [#29717]
[#29717]: https://github.com/rust-lang/rust/issues/29717
------------------------

View File

@ -1,10 +0,0 @@
# `cfg_target_has_atomic`
The tracking issue for this feature is: [#32976]
[#32976]: https://github.com/rust-lang/rust/issues/32976
------------------------

View File

@ -1,10 +0,0 @@
# `cfg_target_thread_local`
The tracking issue for this feature is: [#29594]
[#29594]: https://github.com/rust-lang/rust/issues/29594
------------------------

View File

@ -1,10 +0,0 @@
# `cfg_target_feature`
The tracking issue for this feature is: [#29717]
[#29717]: https://github.com/rust-lang/rust/issues/29717
------------------------

View File

@ -1,10 +0,0 @@
# `custom_attribute`
The tracking issue for this feature is: [#29642]
[#29642]: https://github.com/rust-lang/rust/issues/29642
------------------------

View File

@ -1,10 +0,0 @@
# `custom_derive`
The tracking issue for this feature is: [#29644]
[#29644]: https://github.com/rust-lang/rust/issues/29644
------------------------

View File

@ -1,10 +0,0 @@
# `decl_macro`
The tracking issue for this feature is: [#39412]
[#39412]: https://github.com/rust-lang/rust/issues/39412
------------------------

View File

@ -1,10 +0,0 @@
# `default_type_parameter_fallback`
The tracking issue for this feature is: [#27336]
[#27336]: https://github.com/rust-lang/rust/issues/27336
------------------------

View File

@ -1,10 +0,0 @@
# `drop_types_in_const`
The tracking issue for this feature is: [#33156]
[#33156]: https://github.com/rust-lang/rust/issues/33156
------------------------

View File

@ -1,10 +0,0 @@
# `dropck_eyepatch`
The tracking issue for this feature is: [#34761]
[#34761]: https://github.com/rust-lang/rust/issues/34761
------------------------

View File

@ -1,10 +0,0 @@
# `dropck_parametricity`
The tracking issue for this feature is: [#28498]
[#28498]: https://github.com/rust-lang/rust/issues/28498
------------------------

View File

@ -1,10 +0,0 @@
# `exclusive_range_pattern`
The tracking issue for this feature is: [#37854]
[#37854]: https://github.com/rust-lang/rust/issues/37854
------------------------

View File

@ -1,10 +0,0 @@
# `fundamental`
The tracking issue for this feature is: [#29635]
[#29635]: https://github.com/rust-lang/rust/issues/29635
------------------------

View File

@ -1,10 +0,0 @@
# `generic_param_attrs`
The tracking issue for this feature is: [#34761]
[#34761]: https://github.com/rust-lang/rust/issues/34761
------------------------

View File

@ -1,10 +0,0 @@
# `link_cfg`
The tracking issue for this feature is: [#37406]
[#37406]: https://github.com/rust-lang/rust/issues/37406
------------------------

View File

@ -1,10 +0,0 @@
# `link_llvm_intrinsics`
The tracking issue for this feature is: [#29602]
[#29602]: https://github.com/rust-lang/rust/issues/29602
------------------------

View File

@ -1,10 +0,0 @@
# `linkage`
The tracking issue for this feature is: [#29603]
[#29603]: https://github.com/rust-lang/rust/issues/29603
------------------------

View File

@ -1,10 +0,0 @@
# `log_syntax`
The tracking issue for this feature is: [#29598]
[#29598]: https://github.com/rust-lang/rust/issues/29598
------------------------

View File

@ -1,10 +0,0 @@
# `macro_reexport`
The tracking issue for this feature is: [#29638]
[#29638]: https://github.com/rust-lang/rust/issues/29638
------------------------

View File

@ -1,10 +0,0 @@
# `main`
The tracking issue for this feature is: [#29634]
[#29634]: https://github.com/rust-lang/rust/issues/29634
------------------------

View File

@ -1,10 +0,0 @@
# `naked_functions`
The tracking issue for this feature is: [#32408]
[#32408]: https://github.com/rust-lang/rust/issues/32408
------------------------

View File

@ -1,10 +0,0 @@
# `needs_allocator`
The tracking issue for this feature is: [#27389]
[#27389]: https://github.com/rust-lang/rust/issues/27389
------------------------

View File

@ -1,10 +0,0 @@
# `needs_panic_runtime`
The tracking issue for this feature is: [#32837]
[#32837]: https://github.com/rust-lang/rust/issues/32837
------------------------

View File

@ -1,10 +0,0 @@
# `never_type`
The tracking issue for this feature is: [#35121]
[#35121]: https://github.com/rust-lang/rust/issues/35121
------------------------

View File

@ -1,10 +0,0 @@
# `no_core`
The tracking issue for this feature is: [#29639]
[#29639]: https://github.com/rust-lang/rust/issues/29639
------------------------

View File

@ -1,10 +0,0 @@
# `no_debug`
The tracking issue for this feature is: [#29721]
[#29721]: https://github.com/rust-lang/rust/issues/29721
------------------------

View File

@ -1,6 +0,0 @@
# `omit_gdb_pretty_printer_section`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,9 +0,0 @@
# `optin_builtin_traits`
The tracking issue for this feature is: [#13231]
[#13231]: https://github.com/rust-lang/rust/issues/13231
------------------------

View File

@ -1,7 +0,0 @@
# `overlapping_marker_traits`
The tracking issue for this feature is: [#29864]
[#29864]: https://github.com/rust-lang/rust/issues/29864
------------------------

View File

@ -1,10 +0,0 @@
# `panic_runtime`
The tracking issue for this feature is: [#32837]
[#32837]: https://github.com/rust-lang/rust/issues/32837
------------------------

View File

@ -1,10 +0,0 @@
# `placement_in_syntax`
The tracking issue for this feature is: [#27779]
[#27779]: https://github.com/rust-lang/rust/issues/27779
------------------------

View File

@ -1,10 +0,0 @@
# `platform_intrinsics`
The tracking issue for this feature is: [#27731]
[#27731]: https://github.com/rust-lang/rust/issues/27731
------------------------

View File

@ -1,6 +0,0 @@
# `prelude_import`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,10 +0,0 @@
# `quote`
The tracking issue for this feature is: [#29601]
[#29601]: https://github.com/rust-lang/rust/issues/29601
------------------------

View File

@ -1,11 +0,0 @@
# `repr_align`
The tracking issue for this feature is: [#33626]
[#33626]: https://github.com/rust-lang/rust/issues/33626
------------------------

View File

@ -1,10 +0,0 @@
# `repr_simd`
The tracking issue for this feature is: [#27731]
[#27731]: https://github.com/rust-lang/rust/issues/27731
------------------------

View File

@ -1,10 +0,0 @@
# `rustc_attrs`
The tracking issue for this feature is: [#29642]
[#29642]: https://github.com/rust-lang/rust/issues/29642
------------------------

View File

@ -1,6 +0,0 @@
# `rustc_diagnostic_macros`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,6 +0,0 @@
# `sanitizer_runtime`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,10 +0,0 @@
# `simd_ffi`
The tracking issue for this feature is: [#27731]
[#27731]: https://github.com/rust-lang/rust/issues/27731
------------------------

View File

@ -1,10 +0,0 @@
# `simd`
The tracking issue for this feature is: [#27731]
[#27731]: https://github.com/rust-lang/rust/issues/27731
------------------------

View File

@ -1,10 +0,0 @@
# `specialization`
The tracking issue for this feature is: [#31844]
[#31844]: https://github.com/rust-lang/rust/issues/31844
------------------------

View File

@ -1,6 +0,0 @@
# `staged_api`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,10 +0,0 @@
# `start`
The tracking issue for this feature is: [#29633]
[#29633]: https://github.com/rust-lang/rust/issues/29633
------------------------

View File

@ -1,10 +0,0 @@
# `static_nobundle`
The tracking issue for this feature is: [#37403]
[#37403]: https://github.com/rust-lang/rust/issues/37403
------------------------

View File

@ -1,10 +0,0 @@
# `stmt_expr_attributes`
The tracking issue for this feature is: [#15701]
[#15701]: https://github.com/rust-lang/rust/issues/15701
------------------------

View File

@ -1,10 +0,0 @@
# `structural_match`
The tracking issue for this feature is: [#31434]
[#31434]: https://github.com/rust-lang/rust/issues/31434
------------------------

View File

@ -1,6 +0,0 @@
# `target_feature`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,10 +0,0 @@
# `thread_local`
The tracking issue for this feature is: [#29594]
[#29594]: https://github.com/rust-lang/rust/issues/29594
------------------------

View File

@ -1,10 +0,0 @@
# `trace_macros`
The tracking issue for this feature is: [#29598]
[#29598]: https://github.com/rust-lang/rust/issues/29598
------------------------

View File

@ -1,10 +0,0 @@
# `type_ascription`
The tracking issue for this feature is: [#23416]
[#23416]: https://github.com/rust-lang/rust/issues/23416
------------------------

View File

@ -1,10 +0,0 @@
# `unboxed_closures`
The tracking issue for this feature is: [#29625]
[#29625]: https://github.com/rust-lang/rust/issues/29625
------------------------

View File

@ -1,10 +0,0 @@
# `untagged_unions`
The tracking issue for this feature is: [#32836]
[#32836]: https://github.com/rust-lang/rust/issues/32836
------------------------

View File

@ -1,6 +0,0 @@
# `unwind_attributes`
The tracking issue for this feature is: None.
------------------------

View File

@ -1,10 +0,0 @@
# `use_extern_macros`
The tracking issue for this feature is: [#35896]
[#35896]: https://github.com/rust-lang/rust/issues/35896
------------------------

View File

@ -1,7 +0,0 @@
# `alloc`
The tracking issue for this feature is: [#27783]
[#27783]: https://github.com/rust-lang/rust/issues/27783
------------------------

View File

@ -1,8 +0,0 @@
# `as_c_str`
The tracking issue for this feature is: [#40380]
[#40380]: https://github.com/rust-lang/rust/issues/40380
------------------------

View File

@ -1,5 +0,0 @@
# `ascii_ctype`
The tracking issue for this feature is: [#39658]
[#39658]: https://github.com/rust-lang/rust/issues/39658

View File

@ -1,7 +0,0 @@
# `box_heap`
The tracking issue for this feature is: [#27779]
[#27779]: https://github.com/rust-lang/rust/issues/27779
------------------------

View File

@ -1,7 +0,0 @@
# `char_escape_debug`
The tracking issue for this feature is: [#35068]
[#35068]: https://github.com/rust-lang/rust/issues/35068
------------------------

View File

@ -1,7 +0,0 @@
# `coerce_unsized`
The tracking issue for this feature is: [#27732]
[#27732]: https://github.com/rust-lang/rust/issues/27732
------------------------

View File

@ -1,7 +0,0 @@
# `collection_placement`
The tracking issue for this feature is: [#30172]
[#30172]: https://github.com/rust-lang/rust/issues/30172
------------------------

View File

@ -1,7 +0,0 @@
# `collections_range`
The tracking issue for this feature is: [#30877]
[#30877]: https://github.com/rust-lang/rust/issues/30877
------------------------

View File

@ -1,7 +0,0 @@
# `command_envs`
The tracking issue for this feature is: [#38526]
[#38526]: https://github.com/rust-lang/rust/issues/38526
------------------------

View File

@ -1,7 +0,0 @@
# `concat_idents_macro`
The tracking issue for this feature is: [#29599]
[#29599]: https://github.com/rust-lang/rust/issues/29599
------------------------

View File

@ -1,7 +0,0 @@
# `core_char_ext`
The tracking issue for this feature is: [#32110]
[#32110]: https://github.com/rust-lang/rust/issues/32110
------------------------

View File

@ -1,7 +0,0 @@
# `core_float`
The tracking issue for this feature is: [#32110]
[#32110]: https://github.com/rust-lang/rust/issues/32110
------------------------

View File

@ -1,7 +0,0 @@
# `core_slice_ext`
The tracking issue for this feature is: [#32110]
[#32110]: https://github.com/rust-lang/rust/issues/32110
------------------------

View File

@ -1,7 +0,0 @@
# `core_str_ext`
The tracking issue for this feature is: [#32110]
[#32110]: https://github.com/rust-lang/rust/issues/32110
------------------------

View File

@ -1,7 +0,0 @@
# `decode_utf8`
The tracking issue for this feature is: [#27783]
[#27783]: https://github.com/rust-lang/rust/issues/27783
------------------------

View File

@ -1,7 +0,0 @@
# `discriminant_value`
The tracking issue for this feature is: [#24263]
[#24263]: https://github.com/rust-lang/rust/issues/24263
------------------------

View File

@ -1,7 +0,0 @@
# `error_type_id`
The tracking issue for this feature is: [#27745]
[#27745]: https://github.com/rust-lang/rust/issues/27745
------------------------

View File

@ -1,7 +0,0 @@
# `exact_size_is_empty`
The tracking issue for this feature is: [#35428]
[#35428]: https://github.com/rust-lang/rust/issues/35428
------------------------

View File

@ -1,7 +0,0 @@
# `fixed_size_array`
The tracking issue for this feature is: [#27778]
[#27778]: https://github.com/rust-lang/rust/issues/27778
------------------------

View File

@ -1,7 +0,0 @@
# `float_bits_conv`
The tracking issue for this feature is: [#40470]
[#40470]: https://github.com/rust-lang/rust/issues/40470
------------------------

View File

@ -1,7 +0,0 @@
# `fmt_flags_align`
The tracking issue for this feature is: [#27726]
[#27726]: https://github.com/rust-lang/rust/issues/27726
------------------------

View File

@ -1,7 +0,0 @@
# `fn_traits`
The tracking issue for this feature is: [#29625]
[#29625]: https://github.com/rust-lang/rust/issues/29625
------------------------

View File

@ -1,7 +0,0 @@
# `fnbox`
The tracking issue for this feature is: [#28796]
[#28796]: https://github.com/rust-lang/rust/issues/28796
------------------------

View File

@ -1,7 +0,0 @@
# `from_utf8_error_as_bytes`
The tracking issue for this feature is: [#40895]
[#40895]: https://github.com/rust-lang/rust/issues/40895
------------------------

View File

@ -1,7 +0,0 @@
# `fused`
The tracking issue for this feature is: [#35602]
[#35602]: https://github.com/rust-lang/rust/issues/35602
------------------------

View File

@ -1,7 +0,0 @@
# `get_type_id`
The tracking issue for this feature is: [#27745]
[#27745]: https://github.com/rust-lang/rust/issues/27745
------------------------

View File

@ -1,7 +0,0 @@
# `heap_api`
The tracking issue for this feature is: [#27700]
[#27700]: https://github.com/rust-lang/rust/issues/27700
------------------------

View File

@ -1,7 +0,0 @@
# `i128`
The tracking issue for this feature is: [#35118]
[#35118]: https://github.com/rust-lang/rust/issues/35118
------------------------

View File

@ -1,7 +0,0 @@
# `inclusive_range`
The tracking issue for this feature is: [#28237]
[#28237]: https://github.com/rust-lang/rust/issues/28237
------------------------

View File

@ -1,7 +0,0 @@
# `integer_atomics`
The tracking issue for this feature is: [#32976]
[#32976]: https://github.com/rust-lang/rust/issues/32976
------------------------

View File

@ -1,7 +0,0 @@
# `into_boxed_c_str`
The tracking issue for this feature is: [#40380]
[#40380]: https://github.com/rust-lang/rust/issues/40380
------------------------

View File

@ -1,7 +0,0 @@
# `into_boxed_os_str`
The tracking issue for this feature is: [#into_boxed_os_str]
[#into_boxed_os_str]: https://github.com/rust-lang/rust/issues/40380
------------------------

Some files were not shown because too many files have changed in this diff Show More