Render token type names using Token! macro in documentation

dtolnay · Oct 23, 2024 · 3901268 · 3901268
1 parent bd28fa8
commit 3901268
Show file tree

Hide file tree

Showing 5 changed files with 1,087 additions and 1 deletion.
diff --git a/Cargo.toml b/Cargo.toml
@@ -70,7 +70,32 @@ required-features = ["full", "parsing"]
 [package.metadata.docs.rs]
 all-features = true
 targets = ["x86_64-unknown-linux-gnu"]
-rustdoc-args = ["--generate-link-to-definition"]
+rustdoc-args = ["--generate-link-to-definition", "--extend-css=src/gen/token.css"]
+#        --markdown-css FILES
+#                        CSS files to include via <link> in a rendered Markdown
+#                        file
+#        --html-in-header FILES
+#                        files to include inline in the <head> section of a
+#                        rendered Markdown file or generated documentation
+#        --html-before-content FILES
+#                        files to include inline between <body> and the content
+#                        of a rendered Markdown file or generated documentation
+#        --html-after-content FILES
+#                        files to include inline between the content and
+#                        </body> of a rendered Markdown file or generated
+#                        documentation
+#        --markdown-before-content FILES
+#                        files to include inline between <body> and the content
+#                        of a rendered Markdown file or generated documentation
+#        --markdown-after-content FILES
+#                        files to include inline between the content and
+#                        </body> of a rendered Markdown file or generated
+#                        documentation
+#    -e, --extend-css PATH
+#                        To add some CSS rules with a given file to generate
+#                        doc with your own theme. However, your theme might
+#                        break if the rustdoc's generated HTML changes, so be
+#                        careful!
 
 [package.metadata.playground]
 features = ["full", "visit", "visit-mut", "fold", "extra-traits"]

diff --git a/codegen/Cargo.toml b/codegen/Cargo.toml
@@ -14,6 +14,7 @@ json = ["syn-codegen/serde"]
 anyhow = "1"
 color-backtrace = "0.6"
 indexmap = { version = "2", features = ["serde"] }
+indoc = "2"
 inflections = "1.1"
 prettyplease = "0.2.3"
 proc-macro2 = { version = "1.0.20", features = ["span-locations"] }

diff --git a/codegen/src/css.rs b/codegen/src/css.rs
@@ -0,0 +1,49 @@
+use crate::workspace_path;
+use anyhow::Result;
+use indoc::{formatdoc, indoc};
+use std::fs;
+use syn_codegen::Definitions;
+
+pub fn generate(defs: &Definitions) -> Result<()> {
+    let mut styles = String::new();
+    for ty in defs.tokens.keys() {
+        styles += &format!("a.struct[title=\"struct syn::token::{ty}\"],\n");
+    }
+    styles.truncate(styles.len() - 2);
+    styles += indoc! {"
+         {
+        \tdisplay: inline-block;
+        \tcolor: transparent;
+        \twhite-space: nowrap;
+        }
+    "};
+    styles.push('\n');
+    for ty in defs.tokens.keys() {
+        styles += &format!("a.struct[title=\"struct syn::token::{ty}\"]::before,\n");
+    }
+    styles.truncate(styles.len() - 2);
+    styles += indoc! {"
+         {
+        \tdisplay: inline-block;
+        \tcolor: var(--type-link-color);
+        \twidth: 0;
+        }
+    "};
+    for (ty, repr) in &defs.tokens {
+        let padding = ".".repeat((repr.len() + 8).saturating_sub(ty.len()));
+        styles += &formatdoc! {"
+
+            a.struct[title=\"struct syn::token::{ty}\"]::before {{
+            \tcontent: \"Token![{repr}]\";
+            }}
+
+            a.struct[title=\"struct syn::token::{ty}\"]::after {{
+            \tcontent: \"{padding}\";
+            }}
+        "};
+    }
+
+    let css_path = workspace_path::get("src/gen/token.css");
+    fs::write(css_path, styles)?;
+    Ok(())
+}
diff --git a/codegen/src/main.rs b/codegen/src/main.rs
@@ -21,6 +21,7 @@
 
 mod cfg;
 mod clone;
+mod css;
 mod debug;
 mod eq;
 mod file;
@@ -52,5 +53,6 @@ fn main() -> anyhow::Result<()> {
     visit::generate(&defs)?;
     visit_mut::generate(&defs)?;
     snapshot::generate(&defs)?;
+    css::generate(&defs)?;
     Ok(())
 }