Generate features docs from source

xtask/src/codegen.rs

@@ -8,14 +8,15 @@
 mod gen_syntax;
 mod gen_parser_tests;
 mod gen_assists_docs;
+mod gen_feature_docs;
 
 use std::{mem, path::Path};
 
 use crate::{not_bash::fs2, Result};
 
 pub use self::{
-    gen_assists_docs::generate_assists_docs, gen_parser_tests::generate_parser_tests,
-    gen_syntax::generate_syntax,
+    gen_assists_docs::generate_assists_docs, gen_feature_docs::generate_feature_docs,
+    gen_parser_tests::generate_parser_tests, gen_syntax::generate_syntax,
 };
 
 const GRAMMAR_DIR: &str = "crates/ra_parser/src/grammar";

xtask/src/codegen/gen_feature_docs.rs

@@ -0,0 +1,72 @@
+//! Generates `assists.md` documentation.
+
+use std::{fmt, fs, path::PathBuf};
+
+use crate::{
+    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
+    project_root, rust_files, Result,
+};
+
+pub fn generate_feature_docs(mode: Mode) -> Result<()> {
+    let features = Feature::collect()?;
+    let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+
+    let dst = project_root().join("docs/user/generated_features.adoc");
+    codegen::update(&dst, &contents, mode)?;
+    Ok(())
+}
+
+#[derive(Debug)]
+struct Feature {
+    id: String,
+    path: PathBuf,
+    doc: String,
+}
+
+impl Feature {
+    fn collect() -> Result<Vec<Feature>> {
+        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<Feature>, path: PathBuf) -> Result<()> {
+            let text = fs::read_to_string(&path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text);
+
+            for block in comment_blocks {
+                let id = block.id;
+                assert!(
+                    id.split_ascii_whitespace().all(|it| it.starts_with(char::is_uppercase)),
+                    "bad feature: {}",
+                    id
+                );
+                let doc = block.contents.join("\n");
+                acc.push(Feature { id, path: path.clone(), doc })
+            }
+
+            Ok(())
+        }
+    }
+}
+
+impl fmt::Display for Feature {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "=== {}", self.id)?;
+        let path = self.path.strip_prefix(&project_root()).unwrap();
+        let name = self.path.file_name().unwrap();
+
+        //FIXME: generate line number as well
+        writeln!(
+            f,
+            "**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/{}[{}]",
+            path.display(),
+            name.to_str().unwrap(),
+        )?;
+
+        writeln!(f, "\n{}", self.doc)?;
+        Ok(())
+    }
+}

xtask/src/main.rs

@@ -75,6 +75,7 @@ FLAGS:
             codegen::generate_syntax(Mode::Overwrite)?;
             codegen::generate_parser_tests(Mode::Overwrite)?;
             codegen::generate_assists_docs(Mode::Overwrite)?;
+            codegen::generate_feature_docs(Mode::Overwrite)?;
             Ok(())
         }
         "format" => {