[web][doc] Use external-module-map and merge-modules typedoc plugins

For a future integration with static site generators like Docusaurus or
Vitepress, this commit applies the necessary typedoc configuration and
plugins for a more reasonable output structure. Of course, it can (when
not must) be improved, but it's a good starting point for testing.

In short, this commit

  * Adjusts some typedoc options like sort, navigation, and others.
  * Uses the typedoc-plugin-external-module-map in ordert to avoid
    adding the "@module Whatever" at the beginning of each file
    manually.
  * Uses typedoc-plugin-merge-modules to group docs of the same module
    and category. Since it renames the default exports it makes
    typedoc-plugin-rename-defaults obsolete.
  * Separates client and component documentation processing tasks since
    their organizational structure differs slightly.
  * Creates a new task for running these two.

Despite not been included in this commit, typedoc-plugin-markdwon will
be needed for mentioned integration.

To know more,

  * https://typedoc.org/options/organization/
  * https://github.com/asgerjensen/typedoc-plugin-external-module-map
  * https://github.com/krisztianb/typedoc-plugin-merge-modules
  * https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/typedoc-plugin-markdown
  * https://docusaurus.io/
  * https://vitepress.dev/

web/package.json

@@ -18,7 +18,9 @@
     "stylelint": "stylelint 'src/**/*.{css,scss}'",
     "stylelint:fix": "stylelint --fix 'src/**/*.{css,scss}'",
     "check-types": "tsc --skipLibCheck",
-    "typedoc": "npx typedoc && echo Tip: && echo xdg-open jsdoc.out/index.html",
+    "typedoc": "npm run typedoc:client && npm run typedoc:components",
+    "typedoc:client": "npx typedoc --entryPoints src/client --out jsdoc.out/client",
+    "typedoc:components": "npx typedoc --entryPoints src/components --out jsdoc.out/components",
     "test": "jest"
   },
   "engines": {
@@ -87,8 +89,9 @@
     "ts-jest": "^29.0.3",
     "tsconfig-paths-webpack-plugin": "^4.0.0",
     "typedoc": "^0.25.4",
+    "typedoc-plugin-external-module-map": "^2.0.1",
+    "typedoc-plugin-merge-modules": "^5.1.0",
     "typedoc-plugin-missing-exports": "^2.1.0",
-    "typedoc-plugin-rename-defaults": "^0.7.0",
     "typescript": "^5.3.3",
     "webpack": "^5.89.0",
     "webpack-cli": "^5.1.4",

web/src/App.jsx

@@ -17,6 +17,8 @@
  *
  * To contact SUSE LLC about this file by physical or electronic mail, you may
  * find current contact information at www.suse.com.
+ *
+ *  ".*\/src\/components\/([\\w\\-_]+)\/",
  */
 
 import React, { useEffect, useState } from "react";

web/typedoc.json

@@ -1,23 +1,29 @@
 {
   "$schema": "https://typedoc.org/schema.json",
   "name": "Agama Installer",
-  "entryPoints": [
-    "./src",
-  ],
   "entryPointStrategy": "expand",
   "exclude": [
     "./src/lib"
   ],
-  "excludeNotDocumented": true,
-  "out": "jsdoc.out",
   "plugin": [
-    "typedoc-plugin-missing-exports",
-    "typedoc-plugin-rename-defaults"
+    "typedoc-plugin-external-module-map",
+    "typedoc-plugin-merge-modules",
+  ],
+  "excludeReferences": true,
+  "mergeModulesMergeMode": "module-category",
+  "external-modulemap": [
+    ".*\/src\/(client)\/",
+    ".*\/src\/components\/([\\w\\-_]+)\/",
   ],
   "sort": [
-    "source-order"
+    "alphabetical",
+    "visibility"
   ],
-  "categorizeByGroup": false,
+  "navigation": {
+    "includeCategories": true,
+    "includeGroups": true
+  },
+  "categorizeByGroup": true,
   "navigationLinks": {
     "GitHub": "https://github.com/openSUSE/agama"
   },