Bug 1893718 - Configure jsdoc with a javascript file rather than JSON. r=aleca

It turns out that sphinx_js doesn't really do anything with `jsdoc_config_path`
except pass it along to jsdoc itself, which will happily execute a javascript
module. This saves having to write out a new JSON file in the source directory
when building docs.

Differential Revision: https://phabricator.services.mozilla.com/D208786

--HG--
rename : docs/jsdoc.conf.json => docs/jsdoc.conf.js
extra : amend_source : 71be7a74bfbbad14817e39ea8aeda2db0358a069
extra : absorb_source : 967dcb9111a372a93aba2b06271f75fa3ff95dd5

.eslintignore

@@ -67,6 +67,5 @@ mail/extensions/am-e2e/prefs/e2e-prefs.js
 mail/locales/en-US/all-l10n.js
 mail/components/compose/composer.js
 
-# Ignore files downloaded/generated for building documentation
+# Ignore the jsdoc config file
-docs/_venv
+docs/jsdoc.conf.js
-docs/_build

.hgignore

@@ -46,6 +46,4 @@ third_party/asn1js/node_modules/
 \.ruff_cache/
 
 # Built documentation
-docs/_build
-docs/_venv
 ^rust/target/

docs/conf.py

@@ -4,7 +4,6 @@
 
 # Configuration file for the Sphinx documentation builder.
 
-import json
 import os
 import sys
 
@@ -36,21 +35,7 @@ extensions = [
 ]
 
 js_source_path = "../"
-jsdoc_config_path = "jsdoc.conf.json"
+jsdoc_config_path = "jsdoc.conf.js"
-
-# Exclude third-party directories from JSDoc parsing
-third_party_paths = []
-with open("../tools/lint/ThirdPartyPaths.txt", "r") as file:
-    third_party_paths = ["../" + path.removeprefix("comm/").rstrip() for path in file]
-with open(jsdoc_config_path, "r+") as file:
-    # Extend list of excluded JSDoc paths with third-party paths
-    jsdoc_conf = json.load(file)
-    jsdoc_conf["source"]["exclude"].extend(third_party_paths)
-
-    # Write excluded paths back to JSDoc config
-    file.seek(0)
-    json.dump(jsdoc_conf, file)
-    file.truncate()
 
 myst_enable_extensions = [
     "deflist",

docs/jsdoc.conf.js

@@ -1,4 +1,24 @@
-{
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+
+function readFile(path) {
+  return fs
+    .readFileSync(path, { encoding: "utf-8" })
+    .split("\n")
+    .filter(p => p && !p.startsWith("#"))
+    .map(p => p.replace(/^comm\//, "../"));
+}
+
+const ignorePatterns = [
+  ...readFile(
+    path.join(__dirname, "..", "tools", "lint", "ThirdPartyPaths.txt")
+  ),
+  ...readFile(path.join(__dirname, "..", "tools", "lint", "Generated.txt")),
+];
+
+module.exports = {
   "plugins": [],
   "recurseDepth": 10,
   "source": {
@@ -146,7 +166,9 @@
       "../mailnews/test/resources/MessageGenerator.sys.mjs",
       "../mailnews/test/resources/ServerTestUtils.sys.mjs",
 
-      "../suite"
+      "../suite",
+
+      ...ignorePatterns,
     ],
     "includePattern": ".+\\.m?js(doc)?$",
     "excludePattern": "(^|\\/|\\\\)_"
@@ -154,4 +176,4 @@
   "opts": {
     "recurse": true
   }
-}
+};