feat(derive): Support markdown

Cargo.toml

@@ -204,6 +204,10 @@ name = "cargo-example-derive"
 required-features = ["derive", "color"]
 doc-scrape-examples = true
 
+[[example]]
+name = "markdown-derive"
+required-features = ["derive"]
+
 [[example]]
 name = "escaped-positional"
 required-features = ["cargo"]

clap_derive/Cargo.toml

@@ -33,6 +33,8 @@ syn = { version = "2.0.8", features = ["full"] }
 quote = "1.0.9"
 proc-macro2 = "1.0.69"
 heck = "0.5.0"
+pulldown-cmark = { version = "0.12.2", default-features = false }
+anstyle = "1.0.10"
 
 [features]
 default = []

clap_derive/src/utils/doc_comments.rs

@@ -3,7 +3,7 @@
 //! #[derive(Parser)] works in terms of "paragraphs". Paragraph is a sequence of
 //! non-empty adjacent lines, delimited by sequences of blank (whitespace only) lines.
 
-use std::iter;
+use markdown::parse_markdown;
 
 pub(crate) fn extract_doc_comment(attrs: &[syn::Attribute]) -> Vec<String> {
     // multiline comments (`/** ... */`) may have LFs (`\n`) in them,
@@ -54,58 +54,24 @@ pub(crate) fn format_doc_comment(
     preprocess: bool,
     force_long: bool,
 ) -> (Option<String>, Option<String>) {
-    if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
-        let (short, long) = if preprocess {
-            let paragraphs = split_paragraphs(lines);
-            let short = paragraphs[0].clone();
-            let long = paragraphs.join("\n\n");
-            (remove_period(short), long)
-        } else {
-            let short = lines[..first_blank].join("\n");
-            let long = lines.join("\n");
-            (short, long)
-        };
+    if preprocess {
+        let (short, long) = parse_markdown(lines);
+        let long = long.or_else(|| force_long.then(|| short.clone()));
+
+        (Some(remove_period(short)), long)
+    } else if let Some(first_blank) = lines.iter().position(|s| is_blank(s)) {
+        let short = lines[..first_blank].join("\n");
+        let long = lines.join("\n");
 
         (Some(short), Some(long))
     } else {
-        let (short, long) = if preprocess {
-            let short = merge_lines(lines);
-            let long = force_long.then(|| short.clone());
-            let short = remove_period(short);
-            (short, long)
-        } else {
-            let short = lines.join("\n");
-            let long = force_long.then(|| short.clone());
-            (short, long)
-        };
+        let short = lines.join("\n");
+        let long = force_long.then(|| short.clone());
 
         (Some(short), long)
     }
 }
 
-fn split_paragraphs(lines: &[String]) -> Vec<String> {
-    let mut last_line = 0;
-    iter::from_fn(|| {
-        let slice = &lines[last_line..];
-        let start = slice.iter().position(|s| !is_blank(s)).unwrap_or(0);
-
-        let slice = &slice[start..];
-        let len = slice
-            .iter()
-            .position(|s| is_blank(s))
-            .unwrap_or(slice.len());
-
-        last_line += start + len;
-
-        if len != 0 {
-            Some(merge_lines(&slice[..len]))
-        } else {
-            None
-        }
-    })
-    .collect()
-}
-
 fn remove_period(mut s: String) -> String {
     if s.ends_with('.') && !s.ends_with("..") {
         s.pop();
@@ -117,10 +83,200 @@ fn is_blank(s: &str) -> bool {
     s.trim().is_empty()
 }
 
-fn merge_lines(lines: impl IntoIterator<Item = impl AsRef<str>>) -> String {
-    lines
-        .into_iter()
-        .map(|s| s.as_ref().trim().to_owned())
-        .collect::<Vec<_>>()
-        .join(" ")
+mod markdown {
+    use anstyle::{Reset, Style};
+    use pulldown_cmark::{Event, Options, Parser, Tag, TagEnd};
+    use std::fmt;
+    use std::fmt::Write;
+    use std::ops::AddAssign;
+
+    #[derive(Default)]
+    struct MarkdownWriter {
+        output: String,
+        indentation: usize,
+        styles: Vec<Style>,
+    }
+
+    impl MarkdownWriter {
+        fn newline(&mut self) {
+            self.output.push('\n');
+        }
+        fn endline(&mut self) {
+            if !self.output.ends_with('\n') {
+                self.newline();
+            }
+        }
+
+        fn write_fmt(&mut self, arguments: fmt::Arguments<'_>) {
+            if self.output.ends_with('\n') {
+                write!(self.output, "{0: <1$}", "", self.indentation).unwrap();
+            }
+            self.output.write_fmt(arguments).unwrap();
+        }
+
+        fn start_link(&mut self, dest_url: pulldown_cmark::CowStr<'_>) {
+            write!(self, "\x1B]8;;{dest_url}\x1B\\");
+        }
+        fn end_link(&mut self) {
+            write!(self, "\x1B]8;;\x1B\\");
+        }
+
+        fn start_style(&mut self, style: Style) {
+            self.styles.push(style);
+            write!(self, "{style}");
+        }
+        fn end_style(&mut self, style: Style) {
+            let last_style = self.styles.pop();
+            debug_assert_eq!(last_style.unwrap(), style);
+
+            write!(self, "{Reset}");
+            // Reapplying all, because anstyle doesn't support merging styles
+            // (probably because the ambiguity around colors)
+            // TODO If we decide not to support any colors, we can replace this with
+            // anstyle::Effects and remove the need for applying them all individually.
+            for style in &self.styles {
+                write!(self.output, "{style}").unwrap();
+            }
+        }
+    }
+
+    pub(super) fn parse_markdown(input: &[String]) -> (String, Option<String>) {
+        // Markdown Configuration
+        let parsing_options = Options::ENABLE_STRIKETHROUGH /* TODO UNICODE | Options::ENABLE_SMART_PUNCTUATION */;
+        // Minimal Styling for now, because we cannot configure it
+        let style_heading = Style::new().bold();
+        let style_emphasis = Style::new().italic();
+        let style_strong = Style::new().bold();
+        let style_strike_through = Style::new().strikethrough();
+        let style_link = Style::new().underline();
+        // TODO decide how to style code
+        let style_code = Style::new().dimmed();
+        let tab_width = 2;
+        // TODO UNICODE let list_symbol = '•';
+        let list_symbol = '-';
+
+        let input = input.join("\n");
+        let input = Parser::new_ext(&input, parsing_options);
+
+        let mut short = None;
+
+        let mut writer = MarkdownWriter::default();
+
+        let mut list_indices = Vec::new();
+
+        for event in input {
+            match event {
+                Event::Start(Tag::Paragraph) => { /* nothing to do */ }
+                Event::Start(Tag::Heading { .. }) => writer.start_style(style_heading),
+                Event::Start(
+                    Tag::Image { .. } | Tag::BlockQuote(_) | Tag::CodeBlock(_) | Tag::HtmlBlock,
+                ) => { /* IGNORED */ }
+                Event::Start(Tag::List(list_start)) => {
+                    list_indices.push(list_start);
+                    writer.endline();
+                }
+                Event::Start(Tag::Item) => {
+                    if let Some(Some(index)) = list_indices.last_mut() {
+                        write!(writer, "{index}. ");
+                        index.add_assign(1);
+                    } else {
+                        write!(writer, "{list_symbol} ");
+                    }
+                    writer.indentation += tab_width;
+                }
+                Event::Start(Tag::Emphasis) => writer.start_style(style_emphasis),
+                Event::Start(Tag::Strong) => writer.start_style(style_strong),
+                Event::Start(Tag::Strikethrough) => writer.start_style(style_strike_through),
+                Event::Start(Tag::Link { dest_url, .. }) => {
+                    writer.start_link(dest_url);
+                    writer.start_style(style_link);
+                }
+
+                Event::End(TagEnd::Paragraph) => {
+                    if short.is_none() {
+                        short = Some(writer.output.trim().to_owned());
+                    }
+                    writer.endline();
+                    writer.newline();
+                }
+                Event::End(TagEnd::Heading(..)) => {
+                    writer.end_style(style_heading);
+                    writer.endline();
+                    writer.newline();
+                }
+                Event::End(TagEnd::List(_)) => {
+                    let list = list_indices.pop();
+                    debug_assert!(list.is_some());
+                    if list_indices.is_empty() {
+                        writer.newline();
+                    }
+                }
+                Event::End(TagEnd::Item) => {
+                    writer.indentation -= tab_width;
+                    writer.endline();
+                }
+                Event::End(TagEnd::Emphasis) => writer.end_style(style_emphasis),
+                Event::End(TagEnd::Strong) => writer.end_style(style_strong),
+                Event::End(TagEnd::Strikethrough) => writer.end_style(style_strike_through),
+                Event::End(TagEnd::Link) => {
+                    writer.end_link();
+                    writer.end_style(style_link);
+                }
+                Event::End(
+                    TagEnd::Image | TagEnd::BlockQuote(_) | TagEnd::HtmlBlock | TagEnd::CodeBlock,
+                ) => { /* IGNORED */ }
+
+                Event::Text(segment) => write!(writer, "{segment}"),
+                Event::Code(code) => {
+                    writer.start_style(style_code);
+                    write!(writer, "{code}");
+                    writer.end_style(style_code);
+                }
+                // There is not really anything useful to do with block level html.
+                Event::Html(html) => write!(writer, "{html}"),
+                // At some point we could support custom tags like `<red>`
+                Event::InlineHtml(html) => write!(writer, "{html}"),
+                Event::SoftBreak => write!(writer, " "),
+                Event::HardBreak => writer.endline(),
+                // TODO for anything useful we'd need to know the terminal width
+                Event::Rule => {
+                    writer.endline();
+                    writer.newline();
+                    write!(writer, "---\n\n");
+                }
+                Event::Start(
+                    Tag::FootnoteDefinition(_)
+                    | Tag::DefinitionList
+                    | Tag::DefinitionListTitle
+                    | Tag::DefinitionListDefinition
+                    | Tag::Table(_)
+                    | Tag::TableHead
+                    | Tag::TableRow
+                    | Tag::TableCell
+                    | Tag::MetadataBlock(_),
+                )
+                | Event::End(
+                    TagEnd::FootnoteDefinition
+                    | TagEnd::DefinitionList
+                    | TagEnd::DefinitionListTitle
+                    | TagEnd::DefinitionListDefinition
+                    | TagEnd::Table
+                    | TagEnd::TableHead
+                    | TagEnd::TableRow
+                    | TagEnd::TableCell
+                    | TagEnd::MetadataBlock(_),
+                )
+                | Event::InlineMath(_)
+                | Event::DisplayMath(_)
+                | Event::FootnoteReference(_)
+                | Event::TaskListMarker(_) => {
+                    unimplemented!("feature not enabled {event:?}")
+                }
+            }
+        }
+        let short = short.unwrap_or_else(|| writer.output.trim().to_owned());
+        let long = writer.output.trim();
+        let long = (short != long).then(|| long.to_owned());
+        (short, long)
+    }
 }