From 46292c7cecb0bd957aee48f72b5c1e931ce47b79 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 15:02:12 +0200 Subject: Move assists documentation into the manual --- xtask/src/codegen.rs | 33 ++++++++++++++-- xtask/src/codegen/gen_assists_docs.rs | 71 ++++++++++++++++++----------------- xtask/src/codegen/gen_feature_docs.rs | 22 ++--------- xtask/src/lib.rs | 2 +- 4 files changed, 71 insertions(+), 57 deletions(-) (limited to 'xtask') diff --git a/xtask/src/codegen.rs b/xtask/src/codegen.rs index f47d54125..f3917a244 100644 --- a/xtask/src/codegen.rs +++ b/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() + ) + } +} diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs index 6ebeb8aea..15a02d317 100644 --- a/xtask/src/codegen/gen_assists_docs.rs +++ b/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::>().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, 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 == "#")) diff --git a/xtask/src/codegen/gen_feature_docs.rs b/xtask/src/codegen/gen_feature_docs.rs index dbe583e8e..731e7ecf2 100644 --- a/xtask/src/codegen/gen_feature_docs.rs +++ b/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) } } diff --git a/xtask/src/lib.rs b/xtask/src/lib.rs index 06043d19f..874957885 100644 --- a/xtask/src/lib.rs +++ b/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)?; -- cgit v1.2.3