From 52b19c39e8bdbc0a0ed650aa03358768c6803818 Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Sat, 17 Oct 2020 17:06:42 +0300 Subject: Create xtask module to generate diagnostics docs --- xtask/src/codegen.rs | 3 ++ xtask/src/codegen/gen_diagnostic_docs.rs | 73 ++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) create mode 100644 xtask/src/codegen/gen_diagnostic_docs.rs (limited to 'xtask') diff --git a/xtask/src/codegen.rs b/xtask/src/codegen.rs index 3ee4c1adf..afa703471 100644 --- a/xtask/src/codegen.rs +++ b/xtask/src/codegen.rs @@ -10,6 +10,7 @@ mod gen_parser_tests; mod gen_assists_docs; mod gen_feature_docs; mod gen_features; +mod gen_diagnostic_docs; use std::{ fmt, mem, @@ -21,6 +22,7 @@ use crate::{ensure_rustfmt, project_root, Result}; pub use self::{ gen_assists_docs::{generate_assists_docs, generate_assists_tests}, + gen_diagnostic_docs::generate_diagnostic_docs, gen_feature_docs::generate_feature_docs, gen_features::generate_features, gen_parser_tests::generate_parser_tests, @@ -47,6 +49,7 @@ impl CodegenCmd { generate_assists_tests(Mode::Overwrite)?; generate_assists_docs(Mode::Overwrite)?; generate_feature_docs(Mode::Overwrite)?; + generate_diagnostic_docs(Mode::Overwrite)?; Ok(()) } } diff --git a/xtask/src/codegen/gen_diagnostic_docs.rs b/xtask/src/codegen/gen_diagnostic_docs.rs new file mode 100644 index 000000000..4d630ce8c --- /dev/null +++ b/xtask/src/codegen/gen_diagnostic_docs.rs @@ -0,0 +1,73 @@ +//! Generates `assists.md` documentation. + +use std::{fmt, fs, path::PathBuf}; + +use crate::{ + codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE}, + project_root, rust_files, Result, +}; + +pub fn generate_diagnostic_docs(mode: Mode) -> Result<()> { + let features = Diagnostic::collect()?; + let contents = features.into_iter().map(|it| it.to_string()).collect::>().join("\n\n"); + let contents = format!("//{}\n{}\n", PREAMBLE, contents.trim()); + let dst = project_root().join("docs/user/generated_diagnostic.adoc"); + codegen::update(&dst, &contents, mode)?; + Ok(()) +} + +#[derive(Debug)] +struct Diagnostic { + id: String, + location: Location, + doc: String, +} + +impl Diagnostic { + fn collect() -> Result> { + let mut res = Vec::new(); + for path in rust_files(&project_root()) { + collect_file(&mut res, path)?; + } + res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id)); + return Ok(res); + + fn collect_file(acc: &mut Vec, path: PathBuf) -> Result<()> { + let text = fs::read_to_string(&path)?; + let comment_blocks = extract_comment_blocks_with_empty_lines("Diagnostic", &text); + + for block in comment_blocks { + let id = block.id; + if let Err(msg) = is_valid_diagnostic_name(&id) { + panic!("invalid diagnostic name: {:?}:\n {}", id, msg) + } + let doc = block.contents.join("\n"); + let location = Location::new(path.clone(), block.line); + acc.push(Diagnostic { id, location, doc }) + } + + Ok(()) + } + } +} + +fn is_valid_diagnostic_name(diagnostic: &str) -> Result<(), String> { + let diagnostic = diagnostic.trim(); + if diagnostic.find(char::is_whitespace).is_some() { + return Err("Diagnostic names can't contain whitespace symbols".into()); + } + if diagnostic.chars().any(|c| c.is_ascii_uppercase()) { + return Err("Diagnostic names can't contain uppercase symbols".into()); + } + if diagnostic.chars().any(|c| !c.is_ascii()) { + return Err("Diagnostic can't contain non-ASCII symbols".into()); + } + + Ok(()) +} + +impl fmt::Display for Diagnostic { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc) + } +} -- cgit v1.2.3 From aa9be4d5232f27d285211c0c880259655316d114 Mon Sep 17 00:00:00 2001 From: Igor Aleksanov Date: Mon, 19 Oct 2020 20:58:32 +0300 Subject: Use xshell::read_file instead of fs::read_to_string --- xtask/src/codegen/gen_assists_docs.rs | 4 ++-- xtask/src/codegen/gen_diagnostic_docs.rs | 9 +++++---- xtask/src/codegen/gen_feature_docs.rs | 4 ++-- xtask/src/codegen/gen_parser_tests.rs | 2 +- 4 files changed, 10 insertions(+), 9 deletions(-) (limited to 'xtask') diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs index ff307e2aa..d7c85ebe9 100644 --- a/xtask/src/codegen/gen_assists_docs.rs +++ b/xtask/src/codegen/gen_assists_docs.rs @@ -1,6 +1,6 @@ //! Generates `assists.md` documentation. -use std::{fmt, fs, path::Path}; +use std::{fmt, path::Path}; use crate::{ codegen::{self, extract_comment_blocks_with_empty_lines, reformat, Location, Mode, PREAMBLE}, @@ -39,7 +39,7 @@ impl Assist { return Ok(res); fn collect_file(acc: &mut Vec, path: &Path) -> Result<()> { - let text = fs::read_to_string(path)?; + let text = xshell::read_file(path)?; let comment_blocks = extract_comment_blocks_with_empty_lines("Assist", &text); for block in comment_blocks { diff --git a/xtask/src/codegen/gen_diagnostic_docs.rs b/xtask/src/codegen/gen_diagnostic_docs.rs index 4d630ce8c..00aaea5b7 100644 --- a/xtask/src/codegen/gen_diagnostic_docs.rs +++ b/xtask/src/codegen/gen_diagnostic_docs.rs @@ -1,6 +1,6 @@ //! Generates `assists.md` documentation. -use std::{fmt, fs, path::PathBuf}; +use std::{fmt, path::PathBuf}; use crate::{ codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE}, @@ -8,8 +8,9 @@ use crate::{ }; pub fn generate_diagnostic_docs(mode: Mode) -> Result<()> { - let features = Diagnostic::collect()?; - let contents = features.into_iter().map(|it| it.to_string()).collect::>().join("\n\n"); + let diagnostics = Diagnostic::collect()?; + let contents = + diagnostics.into_iter().map(|it| it.to_string()).collect::>().join("\n\n"); let contents = format!("//{}\n{}\n", PREAMBLE, contents.trim()); let dst = project_root().join("docs/user/generated_diagnostic.adoc"); codegen::update(&dst, &contents, mode)?; @@ -33,7 +34,7 @@ impl Diagnostic { return Ok(res); fn collect_file(acc: &mut Vec, path: PathBuf) -> Result<()> { - let text = fs::read_to_string(&path)?; + let text = xshell::read_file(&path)?; let comment_blocks = extract_comment_blocks_with_empty_lines("Diagnostic", &text); for block in comment_blocks { diff --git a/xtask/src/codegen/gen_feature_docs.rs b/xtask/src/codegen/gen_feature_docs.rs index 341e67c73..065dd33f1 100644 --- a/xtask/src/codegen/gen_feature_docs.rs +++ b/xtask/src/codegen/gen_feature_docs.rs @@ -1,6 +1,6 @@ //! Generates `assists.md` documentation. -use std::{fmt, fs, path::PathBuf}; +use std::{fmt, path::PathBuf}; use crate::{ codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE}, @@ -33,7 +33,7 @@ impl Feature { return Ok(res); fn collect_file(acc: &mut Vec, path: PathBuf) -> Result<()> { - let text = fs::read_to_string(&path)?; + let text = xshell::read_file(&path)?; let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text); for block in comment_blocks { diff --git a/xtask/src/codegen/gen_parser_tests.rs b/xtask/src/codegen/gen_parser_tests.rs index 96fdd9216..19ae949d4 100644 --- a/xtask/src/codegen/gen_parser_tests.rs +++ b/xtask/src/codegen/gen_parser_tests.rs @@ -124,7 +124,7 @@ fn existing_tests(dir: &Path, ok: bool) -> Result Date: Mon, 19 Oct 2020 21:07:40 +0300 Subject: Add generated_diagnostic.adoc to the release.rs and smoke_test_docs_generation --- xtask/src/release.rs | 9 ++++++++- xtask/tests/tidy.rs | 1 + 2 files changed, 9 insertions(+), 1 deletion(-) (limited to 'xtask') diff --git a/xtask/src/release.rs b/xtask/src/release.rs index 14fc1f0dd..3cf0d849f 100644 --- a/xtask/src/release.rs +++ b/xtask/src/release.rs @@ -52,7 +52,14 @@ https://github.com/sponsors/rust-analyzer[GitHub Sponsors]. let path = changelog_dir.join(format!("{}-changelog-{}.adoc", today, changelog_n)); write_file(&path, &contents)?; - for &adoc in ["manual.adoc", "generated_features.adoc", "generated_assists.adoc"].iter() { + for &adoc in [ + "manual.adoc", + "generated_features.adoc", + "generated_assists.adoc", + "generated_diagnostic.adoc", + ] + .iter() + { let src = project_root().join("./docs/user/").join(adoc); let dst = website_root.join(adoc); cp(src, dst)?; diff --git a/xtask/tests/tidy.rs b/xtask/tests/tidy.rs index 460069407..faaef2fd4 100644 --- a/xtask/tests/tidy.rs +++ b/xtask/tests/tidy.rs @@ -42,6 +42,7 @@ fn smoke_test_docs_generation() { // We don't commit docs to the repo, so we can just overwrite in tests. codegen::generate_assists_docs(Mode::Overwrite).unwrap(); codegen::generate_feature_docs(Mode::Overwrite).unwrap(); + codegen::generate_diagnostic_docs(Mode::Overwrite).unwrap(); } #[test] -- cgit v1.2.3