xtask/codegen/
feature_docs.rs

1//! Generates `features_generated.md` documentation.
2
3use std::{fmt, fs, io, path::PathBuf};
4
5use crate::{
6    codegen::{CommentBlock, Location, add_preamble},
7    project_root,
8    util::list_rust_files,
9};
10
11pub(crate) fn generate(check: bool) {
12    let features = Feature::collect().unwrap();
13    // Do not generate docs when run with `--check`
14    if check {
15        return;
16    }
17    let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
18    let contents = add_preamble(crate::flags::CodegenType::FeatureDocs, contents);
19    let dst = project_root().join("docs/book/src/features_generated.md");
20    fs::write(dst, contents).unwrap();
21}
22
23#[derive(Debug)]
24struct Feature {
25    id: String,
26    location: Location,
27    doc: String,
28}
29
30impl Feature {
31    fn collect() -> io::Result<Vec<Feature>> {
32        let crates_dir = project_root().join("crates");
33
34        let mut res = Vec::new();
35        for path in list_rust_files(&crates_dir) {
36            collect_file(&mut res, path)?;
37        }
38        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
39        return Ok(res);
40
41        fn collect_file(acc: &mut Vec<Feature>, path: PathBuf) -> io::Result<()> {
42            let text = std::fs::read_to_string(&path)?;
43            let comment_blocks = CommentBlock::extract("Feature", &text);
44
45            for block in comment_blocks {
46                let id = block.id;
47                if let Err(msg) = is_valid_feature_name(&id) {
48                    panic!("invalid feature name: {id:?}:\n  {msg}")
49                }
50                let doc = block.contents.join("\n");
51                let location = Location { file: path.clone(), line: block.line };
52                acc.push(Feature { id, location, doc })
53            }
54
55            Ok(())
56        }
57    }
58}
59
60fn is_valid_feature_name(feature: &str) -> Result<(), String> {
61    'word: for word in feature.split_whitespace() {
62        for short in ["to", "and"] {
63            if word == short {
64                continue 'word;
65            }
66        }
67        for short in ["To", "And"] {
68            if word == short {
69                return Err(format!("Don't capitalize {word:?}"));
70            }
71        }
72        if !word.starts_with(char::is_uppercase) {
73            return Err(format!("Capitalize {word:?}"));
74        }
75    }
76    Ok(())
77}
78
79impl fmt::Display for Feature {
80    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
81        writeln!(f, "### {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
82    }
83}
xtask/codegen/feature_docs.rs

xtask/codegen/
feature_docs.rs
