Skip to content

Commit fea3576

Browse files
committed
Add top level sections to the Unstable Book.
Prior to this commit, the contents of the Unstable Book were assumed to be unstable features. This commit moves features into 'language features' or 'library features' subsections. It also moves the 'linker_flavor' compiler flag into a new 'Compiler Flags' subsection. Even though it was helpful, I removed the tidy check that cross-references the SUMMARY.md links with the Unstable Book directory contents just because it would be difficult to maintain. Relevant PR: #41142.
1 parent 9f2abad commit fea3576

File tree

236 files changed

+308
-301
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

236 files changed

+308
-301
lines changed

src/Cargo.lock

-3
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

src/doc/guide-plugins.md

+1-1

src/doc/unstable-book/src/SUMMARY.md

+226-224

src/doc/unstable-book/src/the-unstable-book.md

+1-1

src/libsyntax/feature_gate.rs

-3
Original file line numberDiff line numberDiff line change
@@ -344,9 +344,6 @@ declare_features! (
344344
// Used to preserve symbols (see llvm.used)
345345
(active, used, "1.18.0", Some(40289)),
346346

347-
// Hack to document `-Z linker-flavor` in The Unstable Book
348-
(active, linker_flavor, "1.18.0", Some(41142)),
349-
350347
// Allows module-level inline assembly by way of global_asm!()
351348
(active, global_asm, "1.18.0", Some(35119)),
352349

src/tools/linkchecker/main.rs

+6
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,12 @@ fn check(cache: &mut Cache,
147147
return None;
148148
}
149149

150+
// mdbook uses the HTML <base> tag to handle links for subdirectories, which
151+
// linkchecker doesn't support
152+
if file.to_str().unwrap().contains("unstable-book/") {
153+
return None;
154+
}
155+
150156
let res = load_file(cache, root, PathBuf::from(file), SkipRedirect);
151157
let (pretty_file, contents) = match res {
152158
Ok(res) => res,

src/tools/tidy/Cargo.toml

-3
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,3 @@
22
name = "tidy"
33
version = "0.1.0"
44
authors = ["Alex Crichton <[email protected]>"]
5-
6-
[dependencies]
7-
regex = "0.2"

src/tools/tidy/src/main.rs

-2
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,6 @@
1414
//! etc. This is run by default on `make check` and as part of the auto
1515
//! builders.
1616
17-
extern crate regex;
18-
1917
use std::env;
2018
use std::fs;
2119
use std::io::{self, Write};

src/tools/tidy/src/unstable_book.rs

+71-64
Original file line numberDiff line numberDiff line change
@@ -10,35 +10,36 @@
1010

1111
use std::collections::HashSet;
1212
use std::fs;
13-
use std::io::{self, BufRead};
1413
use std::path;
1514
use features::{collect_lang_features, collect_lib_features, Status};
1615

1716
const PATH_STR: &'static str = "doc/unstable-book/src";
1817

19-
const SUMMARY_FILE_NAME: &'static str = "SUMMARY.md";
18+
const LANG_FEATURES_DIR: &'static str = "language-features";
2019

21-
static EXCLUDE: &'static [&'static str; 2] = &[SUMMARY_FILE_NAME, "the-unstable-book.md"];
20+
const LIB_FEATURES_DIR: &'static str = "library-features";
2221

2322
/// Build the path to the Unstable Book source directory from the Rust 'src' directory
2423
fn unstable_book_path(base_src_path: &path::Path) -> path::PathBuf {
2524
base_src_path.join(PATH_STR)
2625
}
2726

28-
/// Build the path to the Unstable Book SUMMARY file from the Rust 'src' directory
29-
fn unstable_book_summary_path(base_src_path: &path::Path) -> path::PathBuf {
30-
unstable_book_path(base_src_path).join(SUMMARY_FILE_NAME)
27+
/// Directory where the features are documented within the Unstable Book source directory
28+
fn unstable_book_lang_features_path(base_src_path: &path::Path) -> path::PathBuf {
29+
unstable_book_path(base_src_path).join(LANG_FEATURES_DIR)
3130
}
3231

33-
/// Open the Unstable Book SUMMARY file
34-
fn open_unstable_book_summary_file(base_src_path: &path::Path) -> fs::File {
35-
fs::File::open(unstable_book_summary_path(base_src_path))
36-
.expect("could not open Unstable Book SUMMARY.md")
32+
/// Directory where the features are documented within the Unstable Book source directory
33+
fn unstable_book_lib_features_path(base_src_path: &path::Path) -> path::PathBuf {
34+
unstable_book_path(base_src_path).join(LIB_FEATURES_DIR)
3735
}
3836

3937
/// Test to determine if DirEntry is a file
4038
fn dir_entry_is_file(dir_entry: &fs::DirEntry) -> bool {
41-
dir_entry.file_type().expect("could not determine file type of directory entry").is_file()
39+
dir_entry
40+
.file_type()
41+
.expect("could not determine file type of directory entry")
42+
.is_file()
4243
}
4344

4445
/// Retrieve names of all lang-related unstable features
@@ -61,75 +62,81 @@ fn collect_unstable_lib_feature_names(base_src_path: &path::Path) -> HashSet<Str
6162
.collect()
6263
}
6364

64-
/// Retrieve names of all unstable features
65-
fn collect_unstable_feature_names(base_src_path: &path::Path) -> HashSet<String> {
66-
collect_unstable_lib_feature_names(base_src_path)
67-
.union(&collect_unstable_lang_feature_names(base_src_path))
68-
.map(|n| n.to_owned())
69-
.collect::<HashSet<_, _>>()
70-
}
71-
72-
/// Retrieve file names of all sections in the Unstable Book with:
73-
///
74-
/// * hyphens replaced by underscores
75-
/// * the markdown suffix ('.md') removed
76-
fn collect_unstable_book_section_file_names(base_src_path: &path::Path) -> HashSet<String> {
77-
fs::read_dir(unstable_book_path(base_src_path))
65+
fn collect_unstable_book_section_file_names(dir: &path::Path) -> HashSet<String> {
66+
fs::read_dir(dir)
7867
.expect("could not read directory")
7968
.into_iter()
8069
.map(|entry| entry.expect("could not read directory entry"))
8170
.filter(dir_entry_is_file)
8271
.map(|entry| entry.file_name().into_string().unwrap())
83-
.filter(|n| EXCLUDE.iter().all(|e| n != e))
8472
.map(|n| n.trim_right_matches(".md").replace('-', "_"))
8573
.collect()
8674
}
8775

88-
/// Retrieve unstable feature names that are in the Unstable Book SUMMARY file
89-
fn collect_unstable_book_summary_links(base_src_path: &path::Path) -> HashSet<String> {
90-
let summary_link_regex =
91-
::regex::Regex::new(r"^- \[(\S+)\]\(\S+\.md\)").expect("invalid regex");
92-
io::BufReader::new(open_unstable_book_summary_file(base_src_path))
93-
.lines()
94-
.map(|l| l.expect("could not read line from file"))
95-
.filter_map(|line| {
96-
summary_link_regex.captures(&line).map(|c| {
97-
c.get(1)
98-
.unwrap()
99-
.as_str()
100-
.to_owned()
101-
})
102-
})
103-
.collect()
76+
/// Retrieve file names of all library feature sections in the Unstable Book with:
77+
///
78+
/// * hyphens replaced by underscores
79+
/// * the markdown suffix ('.md') removed
80+
fn collect_unstable_book_lang_features_section_file_names(base_src_path: &path::Path)
81+
-> HashSet<String> {
82+
collect_unstable_book_section_file_names(&unstable_book_lang_features_path(base_src_path))
83+
}
84+
85+
/// Retrieve file names of all language feature sections in the Unstable Book with:
86+
///
87+
/// * hyphens replaced by underscores
88+
/// * the markdown suffix ('.md') removed
89+
fn collect_unstable_book_lib_features_section_file_names(base_src_path: &path::Path)
90+
-> HashSet<String> {
91+
collect_unstable_book_section_file_names(&unstable_book_lib_features_path(base_src_path))
10492
}
10593

10694
pub fn check(path: &path::Path, bad: &mut bool) {
107-
let unstable_feature_names = collect_unstable_feature_names(path);
108-
let unstable_book_section_file_names = collect_unstable_book_section_file_names(path);
109-
let unstable_book_links = collect_unstable_book_summary_links(path);
110-
111-
// Check for Unstable Book section names with no corresponding SUMMARY.md link
112-
for feature_name in &unstable_book_section_file_names - &unstable_book_links {
113-
tidy_error!(
114-
bad,
115-
"The Unstable Book section '{}' needs to have a link in SUMMARY.md",
116-
feature_name);
117-
}
95+
96+
// Library features
97+
98+
let unstable_lib_feature_names = collect_unstable_lib_feature_names(path);
99+
let unstable_book_lib_features_section_file_names =
100+
collect_unstable_book_lib_features_section_file_names(path);
118101

119102
// Check for unstable features that don't have Unstable Book sections
120-
for feature_name in &unstable_feature_names - &unstable_book_section_file_names {
121-
tidy_error!(
122-
bad,
123-
"Unstable feature '{}' needs to have a section in The Unstable Book",
124-
feature_name);
103+
for feature_name in &unstable_lib_feature_names -
104+
&unstable_book_lib_features_section_file_names {
105+
tidy_error!(bad,
106+
"Unstable library feature '{}' needs to have a section within the \
107+
'library features' section of The Unstable Book",
108+
feature_name);
109+
}
110+
111+
// Check for Unstable Book sections that don't have a corresponding unstable feature
112+
for feature_name in &unstable_book_lib_features_section_file_names -
113+
&unstable_lib_feature_names {
114+
tidy_error!(bad,
115+
"The Unstable Book has a 'library feature' section '{}' which doesn't \
116+
correspond to an unstable library feature",
117+
feature_name)
118+
}
119+
120+
// Language features
121+
122+
let unstable_lang_feature_names = collect_unstable_lang_feature_names(path);
123+
let unstable_book_lang_features_section_file_names =
124+
collect_unstable_book_lang_features_section_file_names(path);
125+
126+
for feature_name in &unstable_lang_feature_names -
127+
&unstable_book_lang_features_section_file_names {
128+
tidy_error!(bad,
129+
"Unstable language feature '{}' needs to have a section within the \
130+
'language features' section of The Unstable Book",
131+
feature_name);
125132
}
126133

127134
// Check for Unstable Book sections that don't have a corresponding unstable feature
128-
for feature_name in &unstable_book_section_file_names - &unstable_feature_names {
129-
tidy_error!(
130-
bad,
131-
"The Unstable Book has a section '{}' which doesn't correspond \
132-
to an unstable feature",
133-
feature_name)
135+
for feature_name in &unstable_book_lang_features_section_file_names -
136+
&unstable_lang_feature_names {
137+
tidy_error!(bad,
138+
"The Unstable Book has a 'language feature' section '{}' which doesn't \
139+
correspond to an unstable language feature",
140+
feature_name)
134141
}
135142
}

0 commit comments

Comments
 (0)