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/gen_assists_docs.rs | 71 ++++++++++++++++++----------------- xtask/src/codegen/gen_feature_docs.rs | 22 ++--------- 2 files changed, 40 insertions(+), 53 deletions(-) (limited to 'xtask/src/codegen') 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) } } -- cgit v1.2.3