Bug 1872974 - Add sphinx-js to in-tree docs. r=rjl

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

--HG--
extra : amend_source : 1afc791e3b91ce300002deada6966aafb72013c1
extra : absorb_source : 483d75fe9c4fa08e57a9badac33a1120c62da3d1

.eslintrc.js

@@ -148,5 +148,10 @@ module.exports = {
         "func-names": "off",
       },
     },
+    {
+      files: ["**"],
+      excludedFiles: [".eslintrc.js"],
+      extends: ["plugin:mozilla/valid-jsdoc"],
+    },
   ],
 };

.readthedocs.yaml

@@ -11,10 +11,13 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+    nodejs: "20"
     # You can also specify other tool versions:
-    # nodejs: "16"
     # rust: "1.55"
     # golang: "1.17"
+  jobs:
+    post_install:
+      - npm install -g jsdoc@~4.0.0
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

docs/conf.py

@@ -4,6 +4,7 @@
 
 # Configuration file for the Sphinx documentation builder.
 
+import json
 import os
 import sys
 
@@ -30,9 +31,27 @@ extensions = [
     "sphinx.ext.graphviz",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    "sphinx_js",
     "bzlink",
 ]
 
+js_source_path = "../"
+jsdoc_config_path = "jsdoc.conf.json"
+
+# 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",
     "fieldlist",

docs/index.rst

@@ -10,6 +10,8 @@ Thunderbird Source Tree Documentation
    :caption: Project Information
    :maxdepth: 1
 
+   build/index
+
    mots/index
 
    l10n/index

docs/jsdoc.conf.json

@@ -0,0 +1,160 @@
+{
+  "plugins": [],
+  "recurseDepth": 10,
+  "source": {
+    "exclude": [
+      "../calendar/base/calendar.js",
+      "../calendar/base/content/calendar-base-view.js",
+      "../calendar/base/content/calendar-multiday-view.js",
+      "../calendar/base/content/calendar-task-tree-view.js",
+      "../calendar/base/content/dialogs/calendar-event-dialog-attendees.js",
+      "../calendar/base/content/dialogs/calendar-event-dialog-recurrence.js",
+      "../calendar/base/content/dialogs/calendar-ics-file-dialog.js",
+      "../calendar/base/content/item-editing/calendar-item-editing.js",
+      "../calendar/base/content/widgets/calendar-filter.js",
+      "../calendar/base/content/widgets/calendar-invitation-panel.js",
+      "../calendar/base/content/widgets/calendar-notifications-setting.js",
+      "../calendar/base/content/widgets/datetimepickers.js",
+      "../calendar/base/modules/calUtils.sys.mjs",
+      "../calendar/base/modules/utils/calDateTimeFormatter.sys.mjs",
+      "../calendar/base/modules/utils/calIteratorUtils.sys.mjs",
+      "../calendar/base/src/CalMetronome.jsm",
+      "../calendar/extract/CalExtractParser.jsm",
+      "../calendar/providers/caldav/modules/CalDavRequest.jsm",
+      "../calendar/providers/caldav/modules/CalDavSession.jsm",
+      "../calendar/providers/storage/CalStorageCachedItemModel.jsm",
+      "../calendar/providers/storage/CalStorageDatabase.jsm",
+      "../calendar/providers/storage/CalStorageItemModel.jsm",
+      "../calendar/providers/storage/CalStorageStatements.jsm",
+      "../calendar/test/browser/browser_eventUndoRedo.js",
+      "../calendar/test/browser/browser_taskUndoRedo.js",
+      "../calendar/test/browser/browser_todayPane.js",
+      "../calendar/test/unit/test_calreadablestreamfactory.js",
+
+      "../chat/chat-prefs.js",
+      "../chat/components/src/imCommands.sys.mjs",
+      "../chat/components/src/logger.sys.mjs",
+      "../chat/modules/OTR.sys.mjs",
+      "../chat/modules/imContentSink.sys.mjs",
+      "../chat/modules/jsProtoHelper.sys.mjs",
+      "../chat/protocols/matrix/matrixAccount.sys.mjs",
+      "../chat/protocols/matrix/matrixCommands.sys.mjs",
+      "../chat/protocols/matrix/matrixMessageContent.sys.mjs",
+      "../chat/protocols/matrix/test/head.js",
+
+      "../mail/app/profile/all-thunderbird.js",
+      "../mail/base/content/FilterListDialog.js",
+      "../mail/base/content/about3Pane.js",
+      "../mail/base/content/sanitize.js",
+      "../mail/base/content/sync.js",
+      "../mail/base/content/widgets/customizable-toolbar.js",
+      "../mail/base/content/widgets/tree-view.mjs",
+      "../mail/base/test/browser/browser_cardsView.js",
+      "../mail/base/test/browser/browser_editMenu.js",
+      "../mail/base/test/browser/browser_spacesToolbar.js",
+      "../mail/branding/tb_beta/pref/thunderbird-branding.js",
+      "../mail/branding/thunderbird/pref/thunderbird-branding.js",
+      "../mail/components/accountcreation/content/accountSetup.js",
+      "../mail/components/accountcreation/modules/AccountCreationUtils.sys.mjs",
+      "../mail/components/accountcreation/modules/ExchangeAutoDiscover.sys.mjs",
+      "../mail/components/accountcreation/modules/FetchConfig.sys.mjs",
+      "../mail/components/accountcreation/modules/FetchHTTP.sys.mjs",
+      "../mail/components/accountcreation/modules/GuessConfig.sys.mjs",
+      "../mail/components/activity/content/activity-widgets.js",
+      "../mail/components/addrbook/content/vcard-edit/edit.mjs",
+      "../mail/components/compose/composer.js",
+      "../mail/components/compose/content/addressingWidgetOverlay.js",
+      "../mail/components/customizableui/CustomizableUI.sys.mjs",
+      "../mail/components/enterprisepolicies/Policies.sys.mjs",
+      "../mail/components/enterprisepolicies/schemas/schema.sys.mjs",
+      "../mail/components/extensions/parent/ext-mail.js",
+      "../mail/components/extensions/test/browser/browser_ext_compose_details_body.js",
+      "../mail/components/extensions/test/browser/browser_ext_menus_context_tools_main_menu.js",
+      "../mail/components/extensions/test/browser/head.js",
+      "../mail/components/im/test/TestProtocol.sys.mjs",
+      "../mail/components/migration/src/ThunderbirdProfileMigrator.jsm",
+      "../mail/components/preferences/messengerLanguages.js",
+      "../mail/components/unifiedtoolbar/content/items/mail-go-button.mjs",
+      "../mail/components/unifiedtoolbar/content/mail-tab-button.mjs",
+      "../mail/components/unifiedtoolbar/modules/CustomizableItems.sys.mjs",
+      "../mail/components/unifiedtoolbar/modules/ToolbarMigration.sys.mjs",
+      "../mail/extensions/am-e2e/prefs/e2e-prefs.js",
+      "../mail/extensions/openpgp/content/modules/cryptoAPI/GnuPGCryptoAPI.jsm",
+      "../mail/extensions/openpgp/content/modules/cryptoAPI/RNPCryptoAPI.jsm",
+      "../mail/extensions/openpgp/content/modules/cryptoAPI/interface.js",
+      "../mail/extensions/openpgp/content/modules/keyRing.jsm",
+      "../mail/extensions/openpgp/content/modules/keyserver.jsm",
+      "../mail/locales/en-US/all-l10n.js",
+      "../mail/modules/CommandController.mjs",
+      "../mail/modules/DBViewWrapper.jsm",
+      "../mail/modules/GlobalPopupNotifications.jsm",
+      "../mail/modules/SearchSpec.jsm",
+      "../mail/modules/UIFontSize.sys.mjs",
+      "../mail/test/browser/attachment/browser_openAttachment.js",
+      "../mail/test/browser/cloudfile/browser_attachmentErrors.js",
+      "../mail/test/browser/composition/browser_attachmentReminder.js",
+      "../mail/test/browser/composition/browser_drafts.js",
+      "../mail/test/browser/composition/browser_multipartRelated.js",
+      "../mail/test/browser/composition/browser_sendFormat.js",
+      "../mail/test/browser/folder-display/browser_messageCommands.js",
+      "../mail/test/browser/folder-display/browser_watchIgnoreThread.js",
+      "../mail/test/browser/folder-widget/browser_messageFilters.js",
+      "../mail/test/browser/message-header/browser_messageHeader.js",
+      "../mail/test/browser/newmailaccount/browser_newmailaccount.js",
+      "../mail/test/browser/shared-modules/ComposeHelpers.jsm",
+
+      "../mailnews/addrbook/modules/LDAPMessage.jsm",
+      "../mailnews/base/src/VirtualFolderWrapper.jsm",
+      "../mailnews/compose/src/MessageSend.jsm",
+      "../mailnews/compose/src/MimeMessageUtils.jsm",
+      "../mailnews/compose/src/MimePart.jsm",
+      "../mailnews/db/gloda/modules/Collection.jsm",
+      "../mailnews/db/gloda/modules/Gloda.jsm",
+      "../mailnews/db/gloda/modules/Gloda.jsm",
+      "../mailnews/db/gloda/modules/GlodaConstants.jsm",
+      "../mailnews/db/gloda/modules/GlodaDataModel.jsm",
+      "../mailnews/db/gloda/modules/GlodaDataModel.jsm",
+      "../mailnews/db/gloda/modules/GlodaDatabind.jsm",
+      "../mailnews/db/gloda/modules/GlodaDatastore.jsm",
+      "../mailnews/db/gloda/modules/GlodaExplicitAttr.jsm",
+      "../mailnews/db/gloda/modules/GlodaFundAttr.jsm",
+      "../mailnews/db/gloda/modules/GlodaIndexer.jsm",
+      "../mailnews/db/gloda/modules/GlodaMsgIndexer.jsm",
+      "../mailnews/db/gloda/modules/GlodaMsgSearcher.jsm",
+      "../mailnews/db/gloda/modules/GlodaQueryClassFactory.jsm",
+      "../mailnews/db/gloda/modules/GlodaUtils.jsm",
+      "../mailnews/db/gloda/modules/IndexMsg.jsm",
+      "../mailnews/db/gloda/modules/MimeMessage.jsm",
+      "../mailnews/db/gloda/modules/NounFreetag.jsm",
+      "../mailnews/db/gloda/modules/NounMimetype.jsm",
+      "../mailnews/db/gloda/modules/NounTag.jsm",
+      "../mailnews/db/gloda/modules/SuffixTree.jsm",
+      "../mailnews/db/gloda/test/unit/resources/GlodaTestHelper.jsm",
+      "../mailnews/db/gloda/test/unit/resources/GlodaTestHelperFunctions.jsm",
+      "../mailnews/extensions/mdn/mdn.js",
+      "../mailnews/imap/src/ImapClient.jsm",
+      "../mailnews/imap/src/ImapIncomingServer.jsm",
+      "../mailnews/imap/src/ImapMessageService.jsm",
+      "../mailnews/import/content/csv-field-map.js",
+      "../mailnews/import/modules/BaseProfileImporter.jsm",
+      "../mailnews/import/modules/ThunderbirdProfileImporter.jsm",
+      "../mailnews/import/test/unit/test_ThunderbirdProfileImporter.js",
+      "../mailnews/jsaccount/modules/JSAccountUtils.jsm",
+      "../mailnews/mailnews.js",
+      "../mailnews/mime/jsmime/jsmime.js",
+      "../mailnews/news/src/NntpClient.jsm",
+      "../mailnews/news/src/NntpMessageService.jsm",
+      "../mailnews/news/src/NntpNewsGroup.jsm",
+      "../mailnews/test/fakeserver/Auth.sys.mjs",
+      "../mailnews/test/resources/MailTestUtils.jsm",
+      "../mailnews/test/resources/MessageGenerator.jsm",
+
+      "../suite"
+    ],
+    "includePattern": ".+\\.m?js(doc|m)?$",
+    "excludePattern": "(^|\\/|\\\\)_"
+  },
+  "opts": {
+    "recurse": true
+  }
+}

docs/requirements.in

@@ -1,4 +1,5 @@
-Sphinx>=5,<6
+Sphinx==7.2.6
-sphinx_rtd_theme
+sphinx_rtd_theme==2.0.0
-myst-parser[linkify]
+sphinx-js==3.2.2
-fluent.pygments>=1,<2
+myst-parser[linkify]==2.0.0
+fluent.pygments==1.0

docs/requirements.txt

@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
-#    pip-compile --resolver=backtracking requirements.in
+#    pip-compile requirements.in
 #
 alabaster==0.7.13
     # via sphinx
@@ -12,7 +12,7 @@ certifi==2022.12.7
     # via requests
 charset-normalizer==3.0.1
     # via requests
-docutils==0.17.1
+docutils==0.20.1
     # via
     #   myst-parser
     #   sphinx
@@ -29,22 +29,29 @@ jinja2==3.1.2
     # via
     #   myst-parser
     #   sphinx
-linkify-it-py==1.0.3
+    #   sphinx-js
+linkify-it-py==2.0.2
     # via myst-parser
-markdown-it-py==2.1.0
+markdown-it-py==3.0.0
     # via
     #   mdit-py-plugins
     #   myst-parser
-markupsafe==2.1.1
+markupsafe==2.0.1
-    # via jinja2
+    # via
-mdit-py-plugins==0.3.3
+    #   jinja2
+    #   sphinx-js
+mdit-py-plugins==0.4.0
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-myst-parser[linkify]==0.18.1
+myst-parser[linkify]==2.0.0
-    # via -r requirements.in
+    # via
+    #   -r requirements.in
+    #   myst-parser
 packaging==23.0
     # via sphinx
+parsimonious==0.10.0
+    # via sphinx-js
 pygments==2.14.0
     # via
     #   fluent-pygments
@@ -53,18 +60,25 @@ pytz==2022.7
     # via babel
 pyyaml==6.0
     # via myst-parser
+regex==2023.12.25
+    # via parsimonious
 requests==2.28.2
     # via sphinx
 six==1.16.0
     # via fluent-pygments
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==5.3.0
+sphinx==7.2.6
     # via
     #   -r requirements.in
     #   myst-parser
+    #   sphinx-js
     #   sphinx-rtd-theme
-sphinx-rtd-theme==1.1.1
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-serializinghtml
+sphinx-js==3.2.2
+    # via -r requirements.in
+sphinx-rtd-theme==2.0.0
     # via -r requirements.in
 sphinxcontrib-applehelp==1.0.3
     # via sphinx
@@ -72,14 +86,14 @@ sphinxcontrib-devhelp==1.0.2
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.0
     # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.3
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.9
     # via sphinx
-typing-extensions==4.4.0
-    # via myst-parser
 uc-micro-py==1.0.1
     # via linkify-it-py
 urllib3==1.26.14