Move JSDoc tooling under tools/jsdoc and document publish workflow (#1447)

- add a dedicated JSDoc toolchain under tools/jsdoc, including the custom template, static assets, landing-page generator, and gh-pages staging script
- switch `npm run docs` to build local versioned docs through tools/jsdoc
- add `docs:gh-pages` to stage published docs by preserving the currently published history from `origin/gh-pages` and regenerating the current workspace version
- add `docs:gh-pages:full` to fully rebuild only the published docs subset from tags, instead of rebuilding every historical release tag
- generate the staged docs landing page automatically from the version directories present in the docs output
- hoist shared staged assets into `build/gh-pages-docs/docs/_static` and keep `.nojekyll` for publishing compatibility
- clarify the maintainer workflow in [tools/jsdoc/README.md](/home/minggang/proj/rclnodejs/tools/jsdoc/README.md), including local docs builds, staged gh-pages builds, full published-history rebuilds, and manual landing-page regeneration
- make small JSDoc comment fixes in [lib/subscription.js](/home/minggang/proj/rclnodejs/lib/subscription.js) and [lib/timer.js](/home/minggang/proj/rclnodejs/lib/timer.js) to improve generated API docs

Fix: #1446

Author: minggangw

lib/subscription.js

@@ -21,9 +21,10 @@ const debug = require('debug')('rclnodejs:subscription');
 
 /**
  * @class - Class representing a ROS 2 Subscription
- * @hideconstructor
  * Includes support for content-filtering topics beginning with the
- * ROS Humble release. To learn more about content-filtering
+ * ROS Humble release. To learn more about content-filtering topics,
+ * see the references below.
+ * @hideconstructor
  * @see {@link Node#options}
  * @see {@link Node#createSubscription}
  * @see {@link https://www.omg.org/spec/DDS/1.4/PDF|DDS 1.4 specification, Annex B}

lib/timer.js

@@ -30,7 +30,8 @@ class Timer {
   }
 
   /**
-   * @type {bigint} - The period of the timer in nanoseconds.
+   * The period of the timer in nanoseconds.
+   * @type {bigint}
    */
   get period() {
     return this._period;

package.json

@@ -24,7 +24,9 @@
     "clean": "node-gyp clean && npx rimraf ./generated",
     "install": "node scripts/install.js",
     "postinstall": "npm run generate-messages",
-    "docs": "cd docs && make",
+    "docs": "make -C tools/jsdoc",
+    "docs:gh-pages": "node tools/jsdoc/regenerate-published-docs.js --branch origin/gh-pages --preserve-published",
+    "docs:gh-pages:full": "node tools/jsdoc/regenerate-published-docs.js --branch origin/gh-pages --full-rebuild",
     "test": "nyc node --expose-gc ./scripts/run_test.js && tsd && npm install --no-save electron && node test/electron/run_test.js",
     "test-idl": "nyc node --expose-gc ./scripts/run_test.js --idl",
     "lint": "eslint && node ./scripts/cpplint.js",

tools/jsdoc/Makefile

@@ -0,0 +1,5 @@
+.PHONY: docs
+
+docs:
+	npx jsdoc --package ../../package.json ../../index.js ../../lib/*.js ../../lib/action/*.js -t . -d ../../docs
+	node ./build-index.js

tools/jsdoc/README.md

@@ -0,0 +1,96 @@
+# JSDoc Workflow
+
+This directory contains the custom JSDoc template, the landing-page generator,
+and the staging script used to prepare the docs content that is published to the
+`gh-pages` branch.
+
+## Commands
+
+### `npm run docs`
+
+Build local docs for the current workspace version.
+
+Output:
+
+- `docs/<current-version>/`
+- `docs/index.html`
+
+Use this to verify the docs for the version currently declared in
+`package.json`.
+
+### `npm run docs:gh-pages`
+
+Stage the publishable docs tree under `build/gh-pages-docs/`.
+
+Behavior:
+
+- reads the currently published version set from `origin/gh-pages`
+- preserves that published history
+- regenerates docs for the current workspace version
+- rebuilds the staged landing page index
+
+This is the normal command to use for a new release.
+
+If you delete `build/` and rerun `npm run docs:gh-pages`, the staged tree will
+still contain all currently published versions. That command recreates
+`build/gh-pages-docs/` by copying the published docs snapshot from
+`origin/gh-pages`, then regenerating only the current workspace version.
+
+### `npm run docs:gh-pages:full`
+
+Fully rebuild the currently published docs history under
+`build/gh-pages-docs/`.
+
+Behavior:
+
+- reads the published version set from `origin/gh-pages`
+- rebuilds only those published versions from tags
+- regenerates docs for the current workspace version
+- rebuilds the staged landing page index
+
+This does **not** rebuild docs for every historical `rclnodejs` tag. It only
+rebuilds the subset that is actually published online.
+
+## New Release Example
+
+For a new release such as `1.9.0`:
+
+1. Update `package.json` to `1.9.0`.
+2. Run `npm run docs`.
+3. Verify the local output in `docs/1.9.0/` and `docs/index.html`.
+4. Run `npm run docs:gh-pages`.
+5. Verify the staged output in:
+   - `build/gh-pages-docs/docs/1.9.0/`
+   - `build/gh-pages-docs/docs/index.html`
+   - `build/gh-pages-docs/.nojekyll`
+6. Publish the contents of `build/gh-pages-docs/` to the `gh-pages` branch.
+
+## Manual Landing Page Rebuild
+
+If the staged docs tree already exists and you only want to rebuild
+`build/gh-pages-docs/docs/index.html`, run `tools/jsdoc/build-index.js` against
+that docs root and point it at the package metadata for the latest published
+version.
+
+Example for published version `1.8.0`:
+
+```bash
+mkdir -p build/gh-pages-docs/.tmp
+git show 1.8.0:package.json > build/gh-pages-docs/.tmp/package-1.8.0.json
+
+export RCLNODEJS_DOCS_ROOT="$PWD/build/gh-pages-docs/docs"
+export RCLNODEJS_DOCS_INDEX_PATH="$PWD/build/gh-pages-docs/docs/index.html"
+export RCLNODEJS_LOCAL_INDEX_PATH=''
+export RCLNODEJS_PACKAGE_JSON_PATH="$PWD/build/gh-pages-docs/.tmp/package-1.8.0.json"
+
+node tools/jsdoc/build-index.js
+rm -rf build/gh-pages-docs/.tmp
+```
+
+## Notes
+
+- The staged publish output keeps shared assets in `build/gh-pages-docs/docs/_static/`.
+- `.nojekyll` must remain in the staged output because the published docs tree
+  uses an underscore-prefixed directory.
+- The live docs index is the source of truth for which versions should remain
+  published.