docs: add jsdoc and rtd build

.flake8

@@ -0,0 +1,6 @@
+[flake8]
+filename =
+    *.py
+max-line-length = 120
+extend-exclude =
+    venv/

.github/workflows/ci.yml

@@ -94,6 +94,26 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           verbose: true
 
+  release:
+    if: ${{ needs.setup_release.outputs.publish_release == 'true' }}
+    needs:
+      - setup_release
+      - build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create Release
+        id: action
+        uses: LizardByte/create-release-action@v2025.102.13208
+        with:
+          allowUpdates: false
+          artifacts: ''
+          body: ${{ needs.setup_release.outputs.release_body }}
+          generateReleaseNotes: ${{ needs.setup_release.outputs.release_generate_release_notes }}
+          name: ${{ needs.setup_release.outputs.release_tag }}
+          prerelease: true
+          tag: ${{ needs.setup_release.outputs.release_tag }}
+          token: ${{ secrets.GH_BOT_TOKEN }}
+
   publish-gpr:
     if: ${{ needs.setup_release.outputs.publish_release == 'true' }}
     needs:

.github/workflows/update-docs.yml

@@ -0,0 +1,96 @@
+---
+# This action is centrally managed in https://github.com/<organization>/.github/
+# Don't make changes to this file in this repo as they will be overwritten with changes made to the same file in
+# the above-mentioned repo.
+
+# Use the `rtd` repository label to identify repositories that should trigger have this workflow.
+# If the project slug is not the repository name, add a repository variable named `READTHEDOCS_SLUG` with the value of
+# the ReadTheDocs project slug.
+
+# Update readthedocs on release events.
+
+name: Update docs
+
+on:
+  release:
+    types: [created, edited, deleted]
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.release.tag_name }}"
+  cancel-in-progress: true
+
+jobs:
+  update-docs:
+    env:
+      RTD_SLUG: ${{ vars.READTHEDOCS_SLUG }}
+      RTD_TOKEN: ${{ secrets.READTHEDOCS_TOKEN }}
+      TAG: ${{ github.event.release.tag_name }}
+    if: >-
+      !github.event.release.draft
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get RTD_SLUG
+        run: |
+          # if the RTD_SLUG is not set, use the repository name in lowercase
+          if [ -z "${RTD_SLUG}" ]; then
+              RTD_SLUG=$(echo "${{ github.event.repository.name }}" | tr '[:upper:]' '[:lower:]')
+          fi
+          echo "RTD_SLUG=${RTD_SLUG}" >> $GITHUB_ENV
+
+      - name: Deactivate deleted release
+        if: >-
+          github.event_name == 'release' &&
+          github.event.action == 'deleted'
+        run: |
+          json_body=$(jq -n \
+            --arg active "false" \
+            --arg hidden "false" \
+            --arg privacy_level "public" \
+            '{active: $active, hidden: $hidden, privacy_level: $privacy_level}')
+
+          curl \
+            -X PATCH \
+            -H "Authorization: Token ${RTD_TOKEN}" \
+              https://readthedocs.org/api/v3/projects/${RTD_SLUG}/versions/${TAG}/ \
+            -H "Content-Type: application/json" \
+            -d "$json_body"
+
+      - name: Check if edited release is latest GitHub release
+        id: check
+        if: >-
+          github.event_name == 'release' &&
+          github.event.action == 'edited'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const latestRelease = await github.rest.repos.getLatestRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+
+            core.setOutput('isLatestRelease', latestRelease.data.tag_name === context.payload.release.tag_name);
+
+      - name: Update RTD project
+        # changing the default branch in readthedocs makes "latest" point to that branch/tag
+        # we can also update other properties like description, etc.
+        if: >-
+          steps.check.outputs.isLatestRelease == 'true'
+        run: |
+          json_body=$(jq -n \
+            --arg default_branch "${TAG}" \
+            --arg description "${{ github.event.repository.description }}" \
+            '{default_branch: $default_branch}')
+
+          # change the default branch to the latest release
+          curl \
+            -X PATCH \
+            -H "Authorization: Token ${RTD_TOKEN}" \
+            -H "Content-Type: application/json" \
+            https://readthedocs.org/api/v3/projects/${RTD_SLUG}/ \
+            -d "$json_body"
+
+          # trigger a build for the latest version
+          curl \
+            -X POST \
+            -H "Authorization: Token ${RTD_TOKEN}" \
+            https://readthedocs.org/api/v3/projects/${RTD_SLUG}/versions/latest/builds/

.gitignore

@@ -10,5 +10,7 @@ junit.xml
 coverage/
 
 # Ignore build artifacts
+_readthedocs/
+build/
 dist/
 lizardbyte-shared-web*.tgz

.readthedocs.yaml

@@ -0,0 +1,31 @@
+---
+version: 2
+build:
+  os: "ubuntu-24.04"
+  tools:
+    nodejs: "22"
+    python: "3.13"
+    ruby: "3.3"
+  commands:
+    - 'echo "output directory: ${READTHEDOCS_OUTPUT}html"'
+    # shared-web build
+    - npm install
+    - npm run build
+    - npm pack
+    - 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 install
+    - cd examples/jekyll && npm run build
+    # doxygen example build
+    - cd examples/doxygen && npm install
+    - cd examples/doxygen && npm run build
+    # sphinx example build
+    - cd examples/sphinx && npm install
+    - cd examples/sphinx && npm run build
+    - cd examples/sphinx && npm run lint
+    # debug output
+    - cd ${READTHEDOCS_OUTPUT}html && ls -la -R

examples/doxygen/Doxyfile

@@ -0,0 +1,55 @@
+DOXYFILE_ENCODING = UTF-8
+
+# project metadata
+DOCSET_BUNDLE_ID = dev.lizardbyte.shared-web.doxygen
+DOCSET_PUBLISHER_ID = dev.lizardbyte.shared-web.doxygen
+DOCSET_PUBLISHER_NAME = LizardByte
+PROJECT_BRIEF = "Example use of @lizardbyte/shared-web in doxygen html."
+PROJECT_ICON = $(READTHEDOCS_OUTPUT)html/favicon.ico
+PROJECT_LOGO = $(READTHEDOCS_OUTPUT)html/logo.png
+PROJECT_NAME = shared-web Doxygen sample
+
+# doxygen-awesome-css
+HTML_COLORSTYLE = LIGHT  # required with Doxygen >= 1.9.5
+HTML_COLORSTYLE_HUE = 209
+HTML_COLORSTYLE_SAT = 255
+HTML_COLORSTYLE_GAMMA = 113
+HTML_COPY_CLIPBOARD = NO  # required for Doxygen >= 1.10.0
+HTML_EXTRA_FILES = ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
+HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
+HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
+HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
+HTML_EXTRA_FILES += ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome-tabs.js
+HTML_EXTRA_STYLESHEET = ./node_modules/@jothepro/doxygen-awesome-css/doxygen-awesome.css
+HTML_HEADER = header.html
+
+# @lizardbyte/shared-web
+HTML_EXTRA_FILES += ./node_modules/@lizardbyte/shared-web/dist/crowdin.js
+HTML_EXTRA_STYLESHEET += ./node_modules/@lizardbyte/shared-web/dist/crowdin-doxygen-css.css
+
+# general settings
+CASE_SENSE_NAMES = YES
+CREATE_SUBDIRS = NO
+DISABLE_INDEX = NO
+FULL_SIDEBAR = NO
+GENERATE_HTML = YES
+GENERATE_LATEX = NO
+GENERATE_TREEVIEW = YES
+GENERATE_XML = NO
+HAVE_DOT = NO
+HTML_OUTPUT = html
+MARKDOWN_ID_STYLE = GITHUB
+MARKDOWN_SUPPORT = YES
+PROJECT_NUMBER = $(READTHEDOCS_VERSION)
+OUTPUT_DIRECTORY = $(READTHEDOCS_OUTPUT)html/doxygen
+RECURSIVE = YES
+WARN_AS_ERROR = FAIL_ON_WARNINGS
+WARN_IF_DOC_ERROR = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_IF_UNDOC_ENUM_VAL = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_NO_PARAMDOC = YES
+WARNINGS = YES
+
+USE_MDFILE_AS_MAINPAGE = sample.md
+INPUT = sample.md

examples/doxygen/header.html

@@ -0,0 +1,96 @@
+<!-- HTML header for doxygen 1.10.0-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<!--BEGIN DISABLE_INDEX-->
+<!--BEGIN FULL_SIDEBAR-->
+<script type="text/javascript">var page_layout=1;</script>
+<!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+<script type="text/javascript" src="$relpath^jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+$treeview
+$search
+$mathjax
+$darkmode
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+$extrastylesheet
+
+<!--LIZARDBYTE/SHARED-WEB START-->
+<script type="text/javascript" src="$relpath^crowdin.js"></script>
+<script type="text/javascript">
+  initCrowdIn('LizardByte-docs', null);
+</script>
+
+<!--DOXYGEN-AWESOME START-->
+<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
+<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
+<script type="text/javascript">
+  DoxygenAwesomeDarkModeToggle.init()
+  DoxygenAwesomeFragmentCopyButton.init()
+  DoxygenAwesomeParagraphLink.init()
+  DoxygenAwesomeInteractiveToc.init()
+  DoxygenAwesomeTabs.init()
+</script>
+<!--DOXYGEN-AWESOME END-->
+</head>
+<body>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr id="projectrow">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td id="projectalign">
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td>
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+     <!--BEGIN !FULL_SIDEBAR-->
+    <td>$searchbox</td>
+     <!--END !FULL_SIDEBAR-->
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+  <!--BEGIN SEARCHENGINE-->
+   <!--BEGIN FULL_SIDEBAR-->
+   <tr><td colspan="2">$searchbox</td></tr>
+   <!--END FULL_SIDEBAR-->
+  <!--END SEARCHENGINE-->
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->

examples/doxygen/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "shared-web-doxygen-example",
+  "version": "0.0.0",
+  "description": "Example use of @lizardbyte/shared-web in doxygen html.",
+  "dependencies": {
+    "@jothepro/doxygen-awesome-css": "github:jothepro/doxygen-awesome-css#v2.3.4",
+    "@lizardbyte/shared-web": "file:../../lizardbyte-shared-web-0.0.0.tgz"
+  },
+  "scripts": {
+    "build": "doxygen Doxyfile"
+  }
+}

examples/doxygen/sample.md

@@ -0,0 +1,33 @@
+# shared-web Doxygen sample
+
+This is a sample project for Doxygen with doxygen-awesome-css theme. This project allows you to visualize how the
+widgets appear in Doxygen documentation.
+
+This will be automatically enabled in our [doxyconfig](https://github.com/LizardByte/doxyconfig) repo.
+
+## Widgets
+
+You can include widgets in your Doxygen documentation by adding the following to your
+Doxyfile (or Doxygen configuration file). You may need to adjust the paths depending on your project structure.
+
+### CrowdIn
+
+Doxyfile:
+```doxygen
+HTML_EXTRA_FILES += ../node_modules/@lizardbyte/shared-web/dist/crowdin.js
+HTML_EXTRA_STYLESHEET += ../node_modules/@lizardbyte/shared-web/dist/crowdin-doxygen-css.css
+```
+
+header.html:
+```html
+<!--LIZARDBYTE/SHARED-WEB START-->
+<script type="text/javascript" src="$relpath^crowdin.js"></script>
+<script type="text/javascript">
+    initCrowdIn('LizardByte-docs', null);
+</script>
+```
+
+<details style="display: none;">
+  <summary></summary>
+  [TOC]
+</details>

examples/jekyll/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec