docs: migrate documentation to Dockle

.gitignore

@@ -3,6 +3,8 @@
 
 # Ignore node_modules
 node_modules/
+/.dockle/
+/_site/
 
 # Ignore test coverage
 junit.xml

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "third-party/dockle"]
+	path = third-party/dockle
+	url = https://github.com/LizardByte/dockle.git
+	branch = master

.readthedocs.yaml

@@ -1,36 +1,32 @@
 ---
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
 version: 2
 build:
   os: "ubuntu-24.04"
   tools:
-    nodejs: "22"
-    python: "3.13"
+    nodejs: "24"
+    python: "miniconda-latest"
     ruby: "3.3"
     rust: "1.91"
-  commands:
-    - 'echo "output directory: ${READTHEDOCS_OUTPUT}html"'
-    # shared-web build
-    - npm ci --ignore-scripts
-    - npm run build
-    - mkdir -p ${READTHEDOCS_OUTPUT}html/dist
-    - cp -r dist/* ${READTHEDOCS_OUTPUT}html/dist
-    # jsdoc build
-    - npm run generate-docs
-    # jekyll example build
-    - 'echo "baseurl: projects/shared-web/$READTHEDOCS_VERSION"/jekyll >> ./examples/jekyll/_config.yml'
-    - cd examples/jekyll && npm ci  # we need to include scripts for postinstall actions
-    - cd examples/jekyll && npm run build
-    # doxygen example build
-    - cd examples/doxygen && npm ci --ignore-scripts
-    - cd examples/doxygen && npm run build
-    # sphinx example 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
+  jobs:
+    build:
+      html:
+        - |
+          if [ -f readthedocs_build.sh ]; then
+            dockle_dir="."
+          else
+            dockle_dir="./third-party/dockle"
+          fi
+          chmod +x "${dockle_dir}/readthedocs_build.sh"
+          export DOCKLE_DIR="${dockle_dir}"
+          "${dockle_dir}/readthedocs_build.sh"
+
+conda:
+  environment: third-party/dockle/environment.yml
+
+submodules:
+  include: all
+  recursive: true

README.md

@@ -65,3 +65,46 @@ icon filenames that contain spaces or other reserved characters.
    ```bash
    npm install @lizardbyte/shared-web --ignore-scripts
    ```
+
+## CrowdIn in JSDoc
+
+Create an initializer such as `docs/crowdin-init.js`:
+
+```javascript
+globalThis.initCrowdIn('LizardByte-docs', 'dockle');
+```
+
+Then configure Dockle to load the CrowdIn assets from either jsDelivr or the installed npm package.
+
+### jsDelivr
+
+```toml
+[targets.jsdoc]
+extra_files = ["docs/crowdin-init.js"]
+extra_stylesheets = ["https://cdn.jsdelivr.net/npm/@lizardbyte/shared-web@latest/dist/crowdin-dockle-css.css"]
+extra_javascript = [
+  "https://cdn.jsdelivr.net/npm/@lizardbyte/shared-web@latest/dist/crowdin.js",
+  "crowdin-init.js",
+]
+```
+
+Replace `latest` with a published package version for immutable URLs.
+
+### npm
+
+Install the package, then configure Dockle to copy and load its assets:
+
+```bash
+npm install --save-dev @lizardbyte/shared-web --ignore-scripts
+```
+
+```toml
+[targets.jsdoc]
+extra_files = [
+  "node_modules/@lizardbyte/shared-web/dist/crowdin.js",
+  "node_modules/@lizardbyte/shared-web/dist/crowdin-dockle-css.css",
+  "docs/crowdin-init.js",
+]
+extra_stylesheets = ["crowdin-dockle-css.css"]
+extra_javascript = ["crowdin.js", "crowdin-init.js"]
+```

dockle.toml

@@ -0,0 +1,65 @@
+[project]
+name = "shared-web"
+version = "0.0.0"
+description = "Shared web assets for LizardByte projects."
+repository = "https://github.com/LizardByte/shared-web"
+logo = "docs/static/logo.png"
+favicon = "docs/static/favicon.ico"
+
+[build]
+output = "_site"
+work = ".dockle"
+strict = true
+clean = true
+
+# This repository dogfoods its unreleased dist assets. Released consumers can
+# use the equivalent jsDelivr URLs shown in the framework examples.
+
+[[targets]]
+name = "jsdoc"
+title = "shared-web JavaScript API"
+framework = "jsdoc"
+source = "src"
+home = true
+
+[targets.jsdoc]
+inputs = ["src"]
+readme = "README.md"
+include_pattern = '.+\.js$'
+extra_files = ["dist/crowdin.js", "dist/crowdin-dockle-css.css", "examples/jsdoc/crowdin-init.js"]
+extra_stylesheets = ["crowdin-dockle-css.css"]
+extra_javascript = ["crowdin.js", "crowdin-init.js"]
+
+[[targets]]
+name = "doxygen"
+title = "Doxygen integration example"
+framework = "doxygen"
+source = "examples/doxygen"
+entry = "sample.md"
+
+[targets.doxygen]
+inputs = ["examples/doxygen/sample.md"]
+extra_stylesheets = ["dist/crowdin-dockle-css.css"]
+extra_files = ["dist/crowdin.js"]
+main_page = "examples/doxygen/sample.md"
+
+[[targets]]
+name = "sphinx"
+title = "Sphinx integration example"
+framework = "sphinx"
+source = "examples/sphinx/source"
+
+[targets.sphinx]
+source_edit_link = "https://github.com/LizardByte/shared-web/blob/master/examples/sphinx/source/{filename}"
+static_paths = ["examples/sphinx/source/_static", "dist"]
+extra_stylesheets = ["crowdin-dockle-css.css"]
+extra_javascript = ["crowdin.js", "js/crowdin.js"]
+
+[[targets]]
+name = "rustdoc"
+title = "rustdoc integration example"
+framework = "rustdoc"
+source = "examples/rustdoc"
+
+[targets.rustdoc]
+extra_files = ["dist/crowdin.js", "dist/crowdin-dockle-css.css"]

eslint.config.mjs

@@ -5,11 +5,14 @@ export default [
   pluginJs.configs.recommended,
   {
     ignores: [
+        ".dockle/**", // generated Dockle work files
         "_readthedocs/**", // generated ReadTheDocs HTML
+        "_site/**", // generated Dockle site
         "coverage/**",
         "dist/**",
         "docs/**", // generated JSDoc output
         "examples/**/build/**", // generated example output
+        "third-party/**", // vendored dependencies
     ],
   },
   {

examples/doxygen/header.html

@@ -27,7 +27,7 @@
 <!--LIZARDBYTE/SHARED-WEB START-->
 <script type="text/javascript" src="$relpath^crowdin.js"></script>
 <script type="text/javascript">
-  initCrowdIn('LizardByte-docs', null);
+  initCrowdIn('LizardByte-docs', 'dockle');
 </script>
 
 <!--DOXYGEN-AWESOME START-->