docs: Update packages and config

.readthedocs.yml

@@ -6,10 +6,10 @@
 version: 2
 
 build:
-  os: "ubuntu-22.04"
+  os: "ubuntu-26.04"
   tools:
-    python: "3.9"
-    nodejs: "20"
+    python: "3.13"
+    nodejs: "26"
   jobs:
     post_install:
       # Install jsdoc prior to build, needed by sphinx-js
@@ -22,4 +22,6 @@ sphinx:
 # Optionally set the version of Python and requirements required to build your docs
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: uv
+      command: sync
+      path: docs/

docs/conf.py

@@ -1,7 +1,6 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
+# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Path setup --------------------------------------------------------------
@@ -19,6 +18,7 @@
 primary_domain = 'js'
 
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'nodejs-itoolkit'
 copyright = '2020, IBM'
@@ -31,6 +31,7 @@
     release = package['version']
 
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -48,9 +49,10 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.venv']
 
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -60,4 +62,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']

docs/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "nodejs-itoolkit-docs"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "sphinx-js >= 2.8",
+    "Sphinx",
+
+    # Pin Jinja2 and markupsafe versions
+    # https://github.com/mozilla/sphinx-js/issues/190
+    # markupsafe==2.0.1
+    # Jinja2>2.0,<3.0
+
+    "sphinx_rtd_theme",
+]

docs/rtd-modules/jsdoc/jsdoc.js

@@ -0,0 +1,28 @@
+// Work around sphinx-js / asdf version manager issue
+// https://github.com/pyodide/sphinx-js/issues/316
+//
+// asdf creates a bash script shim for jsdoc but sphinx-js calls jsdoc through
+// `node path/to/jsdoc ...`, which causes the following error
+//
+// /home/docs/.asdf/shims/jsdoc:2
+// # asdf-plugin: nodejs 26.4.0
+// ^
+// SyntaxError: Invalid or unexpected token
+//
+// We work around this by creating this jsdoc JS script which can be called directly
+// with node which finds the actual jsdoc command and calls it with all its args.
+
+const process = require('node:process');
+const fs = require('fs');
+
+for (const path of process.env.PATH.split(':')) {
+    const jsdoc = path + '/' + 'jsdoc';
+    if (fs.existsSync(jsdoc)) {
+        const args = [jsdoc].concat(process.argv.slice(2));
+
+        process.execve(jsdoc, args);
+    }
+}
+
+console.error("Can't find jsdoc command");
+process.exit(1);