From 2480d608b4cb527a01c463b89b620e626f7108c7 Mon Sep 17 00:00:00 2001
From: BD103 <59022059+BD103@users.noreply.github.com>
Date: Wed, 6 Nov 2024 08:04:18 -0500
Subject: [PATCH] Add CSS for `rustdoc` alerts (#161)
Closes #158, extracted from #152, will be used in #109.
This adds pretty alerts in `rustdoc` for `bevy_lint` that will be used
in #109 when writing `bevy_lint`'s user documentation.
---
.cargo/config.toml | 7 +++
bevy_lint/Cargo.toml | 6 +++
bevy_lint/assets/rustdoc.css | 101 +++++++++++++++++++++++++++++++++++
3 files changed, 114 insertions(+)
create mode 100644 .cargo/config.toml
create mode 100644 bevy_lint/assets/rustdoc.css
diff --git a/.cargo/config.toml b/.cargo/config.toml
new file mode 100644
index 0000000..3c99324
--- /dev/null
+++ b/.cargo/config.toml
@@ -0,0 +1,7 @@
+[alias]
+# Build the documentation for `bevy_lint` with all required flags.
+#
+# - `rustdoc`: allows specifying extra `rustdoc` flags at the cost of not documenting dependencies.
+# - `-p bevy_lint --lib`: documents the `bevy_lint` library.
+# - `--extend-css ...`: includes extra CSS used in the documentation.
+doc-lints = "rustdoc -p bevy_lint --lib -- --extend-css bevy_lint/assets/rustdoc.css"
diff --git a/bevy_lint/Cargo.toml b/bevy_lint/Cargo.toml
index f41f18b..28a4172 100644
--- a/bevy_lint/Cargo.toml
+++ b/bevy_lint/Cargo.toml
@@ -56,3 +56,9 @@ ui_test = "0.27.1"
[package.metadata.rust-analyzer]
# Enables Rust-Analyzer support for `rustc` crates.
rustc_private = true
+
+[package.metadata.docs.rs]
+# Unlike `cargo doc-lints`, docs.rs doesn't know this crate is in a workspace, it just receives the
+# archive resulting from `cargo package`. In this scenario, we do not need to specify `bevy_lint` before
+# `assets/rustdoc.css`.
+rustdoc-args = ["--extend-css", "assets/rustdoc.css"]
diff --git a/bevy_lint/assets/rustdoc.css b/bevy_lint/assets/rustdoc.css
new file mode 100644
index 0000000..e04928b
--- /dev/null
+++ b/bevy_lint/assets/rustdoc.css
@@ -0,0 +1,101 @@
+/*
+ * Extended theme configuration.
+ *
+ * These colors are based off Github's (blue for notes, green for tips, etc.), though the exact
+ * colors are taken from `rustdoc`'s themes.
+ */
+:root[data-theme="light"] {
+ --bevy-alert-note: #2196f3;
+ --bevy-alert-tip: #068000;
+ --bevy-alert-important: #6e4fc9;
+ --bevy-alert-warning: #ff8e00;
+ --bevy-alert-caution: #be2525;
+}
+
+:root[data-theme="dark"] {
+ --bevy-alert-note: #008dfd;
+ --bevy-alert-tip: #2bab63;
+ --bevy-alert-important: #b78cf2;
+ --bevy-alert-warning: #ff8e00;
+ --bevy-alert-caution: #d93d3d;
+}
+
+:root[data-theme="ayu"] {
+ --bevy-alert-note: #39afd7;
+ --bevy-alert-tip: #b8cc52;
+ --bevy-alert-important: #a37acc;
+ --bevy-alert-warning: #ff8e00;
+ --bevy-alert-caution: #df3600;
+}
+
+/* Used to make part of the document hidden in `rustdoc`, but visible in Github. */
+.rustdoc-hidden {
+ display: none;
+}
+
+/*
+ * Alerts are siblings to the `.warning` class, and as such use many of the same rules.
+ *
+ * The first `` in a alert must be the title, as it will be colored and styled differently.
+ *
+ * # Example
+ *
+ * ```
+ *
+ *
+ * > **Fun Fact**
+ * >
+ * > This is a fun 'lil alert! :3
+ *
+ *
+ * ```
+ */
+.rustdoc-alert {
+ border-left: 2px solid;
+ margin: 0 0 0.75em 0;
+ position: relative;
+ overflow-x: visible !important;
+}
+
+/* Remove the existing quote margin and setup some padding instead. */
+.rustdoc-alert blockquote {
+ margin: 0;
+ padding: 14px;
+}
+
+/* Sets up an icon next to the alert, just like `.warning`. */
+.rustdoc-alert::before {
+ content: "ⓘ";
+ position: absolute;
+ left: -25px;
+ top: 5px;
+ font-weight: bold;
+ font-size: 1.25rem;
+}
+
+/* Make the alert title the same sans-serif font and size as headings. */
+.rustdoc-alert blockquote > p:first-child {
+ font-family: "Fira Sans", Arial, NanumBarunGothic, sans-serif;
+ font-size: 1.125rem;
+}
+
+/* Color styles for different kinds of alerts. */
+.rustdoc-alert.rustdoc-alert-note { border-left-color: var(--bevy-alert-note); }
+.rustdoc-alert.rustdoc-alert-note::before { color: var(--bevy-alert-note); }
+.rustdoc-alert.rustdoc-alert-note blockquote > p:first-child { color: var(--bevy-alert-note); }
+
+.rustdoc-alert.rustdoc-alert-tip { border-left-color: var(--bevy-alert-tip); }
+.rustdoc-alert.rustdoc-alert-tip::before { color: var(--bevy-alert-tip); }
+.rustdoc-alert.rustdoc-alert-tip blockquote > p:first-child { color: var(--bevy-alert-tip); }
+
+.rustdoc-alert.rustdoc-alert-important { border-left-color: var(--bevy-alert-important); }
+.rustdoc-alert.rustdoc-alert-important::before { color: var(--bevy-alert-important); }
+.rustdoc-alert.rustdoc-alert-important blockquote > p:first-child { color: var(--bevy-alert-important); }
+
+.rustdoc-alert.rustdoc-alert-warning { border-left-color: var(--bevy-alert-warning); }
+.rustdoc-alert.rustdoc-alert-warning::before { color: var(--bevy-alert-warning); }
+.rustdoc-alert.rustdoc-alert-warning blockquote > p:first-child { color: var(--bevy-alert-warning); }
+
+.rustdoc-alert.rustdoc-alert-caution { border-left-color: var(--bevy-alert-caution); }
+.rustdoc-alert.rustdoc-alert-caution::before { color: var(--bevy-alert-caution); }
+.rustdoc-alert.rustdoc-alert-caution blockquote > p:first-child { color: var(--bevy-alert-caution); }