Merge #4670

4670: Move assists documentation into the manual r=matklad a=matklad



bors r+
🤖

Co-authored-by: Aleksey Kladov <aleksey.kladov@gmail.com>

docs/user/manual.adoc

@@ -278,5 +278,6 @@ include::./generated_features.adoc[]
 
 Assists, or code actions, are small local refactorings, available in a particular context.
 They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
+Cursor position or selection is signified by `┃` character.
 
-See [assists.md](./assists.md) for the list of available assists.
+include::./generated_assists.adoc[]

xtask/src/codegen.rs

@@ -10,9 +10,12 @@ mod gen_parser_tests;
 mod gen_assists_docs;
 mod gen_feature_docs;
 
-use std::{mem, path::Path};
+use std::{
+    fmt, mem,
+    path::{Path, PathBuf},
+};
 
-use crate::{not_bash::fs2, Result};
+use crate::{not_bash::fs2, project_root, Result};
 
 pub use self::{
     gen_assists_docs::generate_assists_docs, gen_feature_docs::generate_feature_docs,
@@ -29,7 +32,6 @@ const AST_TOKENS: &str = "crates/ra_syntax/src/ast/generated/tokens.rs";
 
 const ASSISTS_DIR: &str = "crates/ra_assists/src/handlers";
 const ASSISTS_TESTS: &str = "crates/ra_assists/src/tests/generated.rs";
-const ASSISTS_DOCS: &str = "docs/user/assists.md";
 
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum Mode {
@@ -107,3 +109,28 @@ fn do_extract_comment_blocks(text: &str, allow_blocks_with_empty_lines: bool) ->
     }
     res
 }
+
+#[derive(Debug)]
+struct Location {
+    file: PathBuf,
+}
+
+impl Location {
+    fn new(file: PathBuf) -> Self {
+        Self { file }
+    }
+}
+
+impl fmt::Display for Location {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let path = self.file.strip_prefix(&project_root()).unwrap().display().to_string();
+        let path = path.replace('\\', "/");
+        let name = self.file.file_name().unwrap();
+        write!(
+            f,
+            "https://github.com/rust-analyzer/rust-analyzer/blob/master/{}[{}]",
+            path,
+            name.to_str().unwrap()
+        )
+    }
+}

xtask/src/codegen/gen_assists_docs.rs

@@ -1,22 +1,28 @@
 //! Generates `assists.md` documentation.
 
-use std::{fs, path::Path};
+use std::{fmt, fs, path::Path};
 
 use crate::{
-    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
     project_root, rust_files, Result,
 };
 
 pub fn generate_assists_docs(mode: Mode) -> Result<()> {
     let assists = Assist::collect()?;
     generate_tests(&assists, mode)?;
-    generate_docs(&assists, mode)?;
+
+    let contents = assists.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_assists.adoc");
+    codegen::update(&dst, &contents, mode)?;
+
     Ok(())
 }
 
 #[derive(Debug)]
 struct Assist {
     id: String,
+    location: Location,
     doc: String,
     before: String,
     after: String,
@@ -58,7 +64,8 @@ impl Assist {
                 assert_eq!(lines.next().unwrap().as_str(), "->");
                 assert_eq!(lines.next().unwrap().as_str(), "```");
                 let after = take_until(lines.by_ref(), "```");
-                acc.push(Assist { id, doc, before, after })
+                let location = Location::new(path.to_path_buf());
+                acc.push(Assist { id, location, doc, before, after })
             }
 
             fn take_until<'a>(lines: impl Iterator<Item = &'a String>, marker: &str) -> String {
@@ -76,6 +83,31 @@ impl Assist {
     }
 }
 
+impl fmt::Display for Assist {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let before = self.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
+        let after = self.after.replace("<|>", "┃");
+        writeln!(
+            f,
+            "[discrete]\n=== `{}`
+
+{}
+
+.Before
+```rust
+{}```
+
+.After
+```rust
+{}```",
+            self.id,
+            self.doc,
+            hide_hash_comments(&before),
+            hide_hash_comments(&after)
+        )
+    }
+}
+
 fn generate_tests(assists: &[Assist], mode: Mode) -> Result<()> {
     let mut buf = String::from("use super::check_doc_test;\n");
 
@@ -103,37 +135,6 @@ r#####"
     codegen::update(&project_root().join(codegen::ASSISTS_TESTS), &buf, mode)
 }
 
-fn generate_docs(assists: &[Assist], mode: Mode) -> Result<()> {
-    let mut buf = String::from(
-        "# Assists\n\nCursor position or selection is signified by `┃` character.\n\n",
-    );
-
-    for assist in assists {
-        let before = assist.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
-        let after = assist.after.replace("<|>", "┃");
-        let docs = format!(
-            "
-## `{}`
-
-{}
-
-```rust
-// BEFORE
-{}
-// AFTER
-{}```
-",
-            assist.id,
-            assist.doc,
-            hide_hash_comments(&before),
-            hide_hash_comments(&after)
-        );
-        buf.push_str(&docs);
-    }
-
-    codegen::update(&project_root().join(codegen::ASSISTS_DOCS), &buf, mode)
-}
-
 fn hide_hash_comments(text: &str) -> String {
     text.split('\n') // want final newline
         .filter(|&it| !(it.starts_with("# ") || it == "#"))

xtask/src/codegen/gen_feature_docs.rs

@@ -3,7 +3,7 @@
 use std::{fmt, fs, path::PathBuf};
 
 use crate::{
-    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
     project_root, rust_files, Result,
 };
 
@@ -19,7 +19,7 @@ pub fn generate_feature_docs(mode: Mode) -> Result<()> {
 #[derive(Debug)]
 struct Feature {
     id: String,
-    path: PathBuf,
+    location: Location,
     doc: String,
 }
 
@@ -40,7 +40,7 @@ impl Feature {
                 let id = block.id;
                 assert!(is_valid_feature_name(&id), "invalid feature name: {:?}", id);
                 let doc = block.contents.join("\n");
-                acc.push(Feature { id, path: path.clone(), doc })
+                acc.push(Feature { id, location: Location::new(path.clone()), doc })
             }
 
             Ok(())
@@ -69,20 +69,6 @@ fn is_valid_feature_name(feature: &str) -> bool {
 
 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().display().to_string();
-        let path = path.replace('\\', "/");
-        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,
-            name.to_str().unwrap(),
-        )?;
-
-        writeln!(f, "{}", self.doc)?;
-        Ok(())
+        writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
     }
 }

xtask/src/lib.rs

@@ -191,7 +191,7 @@ Release: release:{}[]
     let path = changelog_dir.join(format!("{}-changelog-{}.adoc", today, changelog_n));
     fs2::write(&path, &contents)?;
 
-    for &adoc in ["manual.adoc", "generated_features.adoc"].iter() {
+    for &adoc in ["manual.adoc", "generated_features.adoc", "generated_assists.adoc"].iter() {
         let src = project_root().join("./docs/user/").join(adoc);
         let dst = website_root.join(adoc);
         fs2::copy(src, dst)?;