feat(examples): add rustdoc example

.gitignore

@@ -12,4 +12,5 @@ coverage/
 _readthedocs/
 build/
 dist/
+target/
 lizardbyte-shared-web*.tgz

.readthedocs.yaml

@@ -6,6 +6,7 @@ build:
     nodejs: "22"
     python: "3.13"
     ruby: "3.3"
+    rust: "1.91"
   commands:
     - 'echo "output directory: ${READTHEDOCS_OUTPUT}html"'
     # shared-web build
@@ -26,5 +27,10 @@ build:
     - cd examples/sphinx && npm ci  # we need to include scripts for postinstall actions
     - cd examples/sphinx && npm run build
     - cd examples/sphinx && npm run lint
+    # rustdoc example build
+    - cd examples/rustdoc && npm ci --ignore-scripts
+    - cd examples/rustdoc && npm run build
+    - mkdir -p ${READTHEDOCS_OUTPUT}html/rustdoc
+    - cp -r examples/rustdoc/build/html/rustdoc/* ${READTHEDOCS_OUTPUT}html/rustdoc/
     # debug output
     - cd ${READTHEDOCS_OUTPUT}html && ls -la -R

eslint.config.mjs

@@ -9,6 +9,7 @@ export default [
         "coverage/**",
         "dist/**",
         "docs/**", // generated JSDoc output
+        "examples/**/build/**", // generated example output
     ],
   },
   {

examples/rustdoc/.cargo/config.toml

@@ -0,0 +1,5 @@
+[build]
+rustdocflags = [
+    "--html-after-content",
+    "rustdoc/shared-web.html",
+]

examples/rustdoc/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "shared-web-rustdoc-example"
+version = "0.0.0"
+edition = "2021"
+description = "Example use of @lizardbyte/shared-web in rustdoc html."
+license = "AGPL-3.0-only"
+publish = false
+exclude = [
+    "build",
+    "node_modules",
+]
+
+[lib]
+name = "shared_web_rustdoc_example"
+path = "src/lib.rs"

examples/rustdoc/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "shared-web-rustdoc-example",
+  "version": "0.0.0",
+  "description": "Example use of @lizardbyte/shared-web in rustdoc html.",
+  "dependencies": {
+    "@lizardbyte/shared-web": "file:../.."
+  },
+  "scripts": {
+    "build": "cargo doc --no-deps --target-dir build/html/rustdoc && node rustdoc/build.js"
+  }
+}

examples/rustdoc/rustdoc/build.js

@@ -0,0 +1,39 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const exampleDir = path.resolve(__dirname, '..');
+const targetDir = path.join(exampleDir, 'build', 'html', 'rustdoc');
+const docDir = path.join(targetDir, 'doc');
+const sharedWebDist = path.join(exampleDir, 'node_modules', '@lizardbyte', 'shared-web', 'dist');
+const sharedWebAssets = [
+    'crowdin.js',
+    'crowdin-rustdoc-css.css',
+];
+
+function findHtmlDirectories(dir) {
+    const directories = new Set();
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    entries.forEach((entry) => {
+        const entryPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            findHtmlDirectories(entryPath).forEach((htmlDir) => directories.add(htmlDir));
+            return;
+        }
+
+        if (entry.isFile() && entry.name.endsWith('.html')) {
+            directories.add(dir);
+        }
+    });
+
+    return directories;
+}
+
+fs.mkdirSync(docDir, { recursive: true });
+
+findHtmlDirectories(docDir).forEach((htmlDir) => {
+    sharedWebAssets.forEach((asset) => {
+        fs.copyFileSync(path.join(sharedWebDist, asset), path.join(htmlDir, asset));
+    });
+});

examples/rustdoc/rustdoc/shared-web.html

@@ -0,0 +1,7 @@
+<!--LIZARDBYTE/SHARED-WEB START-->
+<link rel="stylesheet" href="crowdin-rustdoc-css.css">
+<script src="crowdin.js"></script>
+<script>
+globalThis.initCrowdIn('LizardByte-docs', 'rustdoc');
+</script>
+<!--LIZARDBYTE/SHARED-WEB END-->

examples/rustdoc/src/lib.rs

@@ -0,0 +1,53 @@
+//! # shared-web rustdoc sample
+//!
+//! This is a sample crate for rustdoc. It demonstrates how the shared-web
+//! CrowdIn language selector appears in Rust API documentation.
+//!
+//! ## Widgets
+//!
+//! ### CrowdIn
+//!
+//! Install `@lizardbyte/shared-web`, then create the rustdoc HTML hook at
+//! `rustdoc/shared-web.html` in your crate root. The crate root is the
+//! directory that contains `Cargo.toml`, so this example stores the hook at
+//! `examples/rustdoc/rustdoc/shared-web.html`.
+//!
+//! The hook loads `crowdin.js` and `crowdin-rustdoc-css.css` from the same
+//! directory as each generated HTML page. The example build script copies
+//! those two files beside every generated `.html` file.
+//!
+//! Configure Cargo to pass the hook to rustdoc:
+//!
+//! ```toml
+//! [build]
+//! rustdocflags = [
+//!     "--html-after-content",
+//!     "rustdoc/shared-web.html",
+//! ]
+//! ```
+//!
+//! When adapting this outside the example, copy `crowdin.js` and
+//! `crowdin-rustdoc-css.css` from `node_modules/@lizardbyte/shared-web/dist`
+//! beside each generated rustdoc HTML page, or adjust the hook paths to point
+//! at a location that every generated page can reach.
+
+/// Returns a greeting for the provided project name.
+///
+/// # Examples
+///
+/// ```
+/// let greeting = shared_web_rustdoc_example::greeting("shared-web");
+/// assert_eq!(greeting, "Hello, shared-web!");
+/// ```
+pub fn greeting(project: &str) -> String {
+    format!("Hello, {project}!")
+}
+
+/// Example metadata rendered by rustdoc.
+#[derive(Debug, Eq, PartialEq)]
+pub struct Widget {
+    /// Human-readable widget name.
+    pub name: String,
+    /// Whether the widget is enabled in the rendered page.
+    pub enabled: bool,
+}

jsdoc.json

@@ -16,7 +16,10 @@
       "add_scripts": "window.initCrowdIn('LizardByte-docs', null);",
       "default_theme": "fallback-dark",
       "favicon": "favicon.ico",
-      "include_css": ["./dist/crowdin-clean-jsdoc-css.css"],
+      "include_css": [
+        "./dist/clean-jsdoc-theme-css.css",
+        "./dist/crowdin-clean-jsdoc-css.css"
+      ],
       "include_js": ["./dist/crowdin.js"],
       "menu": [
         {
@@ -40,6 +43,13 @@
           "class": "",
           "id": "sphinx-sample"
         },
+        {
+          "title": "Rustdoc Sample",
+          "link": "rustdoc/doc/shared_web_rustdoc_example",
+          "target": "_blank",
+          "class": "",
+          "id": "rustdoc-sample"
+        },
         {
           "title": "❤ Donate",
           "link": "https://app.lizardbyte.dev",

package.json

@@ -54,8 +54,17 @@
   },
   "jest": {
     "collectCoverageFrom": [
-      "src/**/*.{js,jsx}"
+      "src/**/*.{js,jsx}",
+      "!src/js/*-css.js"
     ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 100,
+        "functions": 100,
+        "lines": 100,
+        "statements": 100
+      }
+    },
     "testEnvironment": "jsdom"
   },
   "scripts": {

src/css/clean-jsdoc-theme.scss

@@ -0,0 +1,32 @@
+.navbar-container .navbar {
+  max-width: 74rem;
+  padding-left: 1.5rem;
+  padding-right: 1.5rem;
+}
+
+.navbar .navbar-left-items {
+  min-width: 0;
+}
+
+.navbar .navbar-item a {
+  padding-left: 0.875rem;
+  padding-right: 0.875rem;
+  white-space: nowrap;
+}
+
+@media screen and (min-width: 65em) and (max-width: 75em) {
+  .navbar .navbar-item a {
+    font-size: 0.8125rem;
+    padding-left: 0.25rem;
+    padding-right: 0.25rem;
+  }
+
+  .navbar .icon-button {
+    padding: 0.25rem;
+  }
+
+  .navbar .navbar-right-item {
+    margin-left: 0;
+    margin-right: 0;
+  }
+}

src/css/crowdin-rustdoc.scss

@@ -0,0 +1,30 @@
+#crowdin-language-picker.rustdoc-crowdin-picker {
+  margin: 1rem;
+  width: calc(100% - 2rem);
+}
+
+#crowdin-language-picker.rustdoc-crowdin-picker .cr-picker-button {
+  box-sizing: border-box;
+  width: 100%;
+}
+
+#crowdin-language-picker .cr-picker-button,
+#crowdin-language-picker .cr-picker-submenu {
+  background-color: var(--sidebar-background-color, var(--main-background-color, #ffffff)) !important;
+  border: 1px solid var(--border-color, #dddddd) !important;
+  color: var(--main-color, #111111) !important;
+}
+
+#crowdin-language-picker .cr-picker-button:hover,
+#crowdin-language-picker .cr-picker-submenu > a:hover {
+  background-color: var(--main-color, #111111) !important;
+  color: var(--main-background-color, #ffffff) !important;
+}
+
+#crowdin-language-picker .cr-picker-submenu > a {
+  color: var(--main-color, #111111) !important;
+}
+
+#crowdin-language-picker .cr-picker-submenu > a.cr-selected {
+  color: var(--link-color, #3873ad) !important;
+}

src/js/clean-jsdoc-theme-css.js

@@ -0,0 +1 @@
+import "../css/clean-jsdoc-theme.scss";

src/js/crowdin-rustdoc-css.js

@@ -0,0 +1 @@
+import "../css/crowdin-rustdoc.scss";