[web][doc] Change the typedoc output (#976)

In general, the Agama documentation start aging bad. It's either, disperse in a bunch of files, outdated, incomplete, or sometimes even wrong. At the time of writing, using a static site generator like [Docusaurus](https://docusaurus.io/) or [Vitepress](https://vitepress.dev) look as good bet to start fixing these problems by putting all the Agama information accessible in a kind of website without too much effort. In that context, with these tools in mind, this PR can be seen a starting point for having a better output of autogenerated documentation. Next steps must include reviewing all the written documentation for fixing and improving at the same time that `@category`, `@internal`, and other [Typedoc tags](https://typedoc.org/guides/tags/) are used correctly for an even better output.
agama-project · Jan 9, 2024 · 2d79033 · 2d79033
2 parents b5b453e + 8fa1935
commit 2d79033
Show file tree

Hide file tree

Showing 19 changed files with 131 additions and 51 deletions.
diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
@@ -51,8 +51,8 @@ jobs:
       - name: Install NPM packages
         run: cd web && npm ci
 
-      - name: Build the JSDoc documentation
-        run: cd web && npm run jsdoc && mv jsdoc.out ../doc/dist/jsdoc
+      - name: Build Web UI documentation
+        run: cd web && npm run typedoc && mv typedoc.out/ ../doc/dist/web-ui
 
       - name: Setup Pages
         uses: actions/configure-pages@v3

diff --git a/doc/index.html b/doc/index.html
@@ -8,7 +8,13 @@
 <body>
   <ul>
     <li><a href="dbus/">D-Bus API</a></li>
-    <li><a href="jsdoc/">Web Fronted Documentation</a></li>
+    <li>
+        Web UI
+        <ul>
+          <li><a href="web-ui/client/">Client</a></li>
+          <li><a href="web-ui/components/">Components</a></li>
+        </ul>
+    </li>
   </ul>
 </body>
 

diff --git a/web/.gitignore b/web/.gitignore
@@ -16,5 +16,5 @@ test/images/
 POTFILES*
 tmp/
 /po/LINGUAS
-/jsdoc.out/
+/typedoc.out/
 /docs/
diff --git a/web/package-lock.json b/web/package-lock.json
diff --git a/web/package.json b/web/package.json
@@ -18,7 +18,9 @@
     "stylelint": "stylelint 'src/**/*.{css,scss}'",
     "stylelint:fix": "stylelint --fix 'src/**/*.{css,scss}'",
     "check-types": "tsc --skipLibCheck",
-    "jsdoc": "npx typedoc --skipErrorChecking --plugin typedoc-plugin-missing-exports src/ src/client/ && 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 typedoc.out/client",
+    "typedoc:components": "npx typedoc --entryPoints src/components --out typedoc.out/components",
     "test": "jest"
   },
   "engines": {
@@ -86,9 +88,11 @@
     "terser-webpack-plugin": "^5.3.9",
     "ts-jest": "^29.0.3",
     "tsconfig-paths-webpack-plugin": "^4.0.0",
-    "typedoc": "^0.25.3",
+    "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",
-    "typescript": "^5.2.2",
+    "typescript": "^5.3.3",
     "webpack": "^5.89.0",
     "webpack-cli": "^5.1.4",
     "webpack-dev-server": "^4.15.1"

diff --git a/web/package/cockpit-agama.changes b/web/package/cockpit-agama.changes
@@ -1,3 +1,10 @@
+-------------------------------------------------------------------
+Mon Jan  8 15:55:39 UTC 2024 - David Diaz <dgonzalez@suse.com>
+
+- Web documentation: improve the auto-generated documentation
+  output to have it ready for a future integration in a static
+  site generator (gh#openSUSE/agama#976).
+
 -------------------------------------------------------------------
 Thu Jan 04 21:44:32 UTC 2024 - Balsa Asanovic <balsaasanovic95@gmail.com>
 

diff --git a/web/src/client/users.js b/web/src/client/users.js
@@ -180,6 +180,9 @@ class UsersBaseClient {
   }
 }
 
+/**
+ * Client to interact with the Agama users service
+ */
 class UsersClient extends WithValidation(UsersBaseClient, USERS_PATH) { }
 
 export { UsersClient };
diff --git a/web/src/components/core/NumericTextInput.jsx b/web/src/components/core/NumericTextInput.jsx
@@ -35,7 +35,7 @@ import { noop } from "~/utils";
  * Helper component for having an input text limited to not signed numbers
  * @component
  *
- * Based on {@link PF/TextInput https://www.patternfly.org/components/forms/text-input}
+ * Based on {@link https://www.patternfly.org/components/forms/text-input PF/TextInput}
  *
  * @note It allows empty value too.
  *

diff --git a/web/src/components/core/Page.jsx b/web/src/components/core/Page.jsx
@@ -37,7 +37,8 @@ import logoUrl from "~/assets/suse-horizontal-logo.svg";
  *
  * @see Page examples.
  *
- * @param {React.ReactNode} [props.children] - a collection of Action components
+ * @param {object} [props] - component props
+ * @param {React.ReactNode} [props.children] - components to be rendered as actions
  */
 const Actions = ({ children }) => <>{children}</>;
 
@@ -58,10 +59,13 @@ const Menu = PageMenu;
  *
  * @see Page examples.
  *
- * @param {React.ReactNode} props.children - content of the action
- * @param {object} [props] - PF/Button props, see {@link https://www.patternfly.org/components/button#props}
+ * @param {object} [props] - Component props.
+ * @param {function} [props.onClick] - Callback to be triggered when action is clicked.
+ * @param {string} [props.navigateTo] - Route to navigate after triggering the onClick callback, if given.
+ * @param {React.ReactNode} props.children - Content of the action.
+ * @param {object} [props.props] - other props passed down to the internal PF/Button. See {@link https://www.patternfly.org/components/button/#button}.
  */
-const Action = ({ children, navigateTo, onClick, ...props }) => {
+const Action = ({ navigateTo, onClick, children, ...props }) => {
   const navigate = useNavigate();
 
   props.onClick = () => {
@@ -82,9 +86,6 @@ const Action = ({ children, navigateTo, onClick, ...props }) => {
  * TODO: Explain below note better
  * @note that we cannot use navigate("..") because our routes are all nested in
  * the root.
- *
- * @param {React.ReactNode} props.children - content of the action
- * @param {object} [props] - {@link Action} props
  */
 const BackAction = () => {
   return (

diff --git a/web/src/components/l10n/KeymapSelector.jsx b/web/src/components/l10n/KeymapSelector.jsx
@@ -26,7 +26,7 @@ import { ListSearch } from "~/components/core";
 import { noop } from "~/utils";
 
 /**
- * @typedef {import ("~/clients/l10n").Keymap} Keymap
+ * @typedef {import ("~/client/l10n").Keymap} Keymap
  */
 
 const ListBox = ({ children, ...props }) => {

diff --git a/web/src/components/l10n/LocaleSelector.jsx b/web/src/components/l10n/LocaleSelector.jsx
@@ -26,7 +26,7 @@ import { ListSearch } from "~/components/core";
 import { noop } from "~/utils";
 
 /**
- * @typedef {import ("~/clients/l10n").Locale} Locale
+ * @typedef {import ("~/client/l10n").Locale} Locale
  */
 
 const ListBox = ({ children, ...props }) => {

diff --git a/web/src/components/l10n/TimezoneSelector.jsx b/web/src/components/l10n/TimezoneSelector.jsx
@@ -26,7 +26,7 @@ import { ListSearch } from "~/components/core";
 import { noop, timezoneTime } from "~/utils";
 
 /**
- * @typedef {import ("~/clients/l10n").Timezone} Timezone
+ * @typedef {import ("~/client/l10n").Timezone} Timezone
  */
 
 const ListBox = ({ children, ...props }) => {

diff --git a/web/src/components/storage/ProposalSettingsSection.jsx b/web/src/components/storage/ProposalSettingsSection.jsx
@@ -39,9 +39,9 @@ import { Icon } from "~/components/layout";
 import { noop } from "~/utils";
 
 /**
- * @typedef {import ("~/clients/storage").ProposalSettings} ProposalSettings
- * @typedef {import ("~/clients/storage").StorageDevice} StorageDevice
- * @typedef {import ("~/clients/storage").Volume} Volume
+ * @typedef {import ("~/client/storage").ProposalManager.ProposalSettings} ProposalSettings
+ * @typedef {import ("~/client/storage").DevicesManager.StorageDevice} StorageDevice
+ * @typedef {import ("~/client/storage").ProposalManager.Volume} Volume
  */
 
 /**

diff --git a/web/src/components/storage/VolumeForm.jsx b/web/src/components/storage/VolumeForm.jsx
@@ -31,6 +31,10 @@ import { FormValidationError, If, NumericTextInput } from '~/components/core';
 import { DEFAULT_SIZE_UNIT, SIZE_METHODS, SIZE_UNITS, parseToBytes, splitSize } from '~/components/storage/utils';
 import { Icon } from "~/components/layout";
 
+/**
+ * @typedef {import ("~/client/storage").ProposalManager.Volume} Volume
+ */
+
 /**
  * Callback function for notifying a form input change
  *
@@ -67,7 +71,7 @@ const SizeUnitFormSelect = ({ units, ...formSelectProps }) => {
  * Based on {@link PF/FormSelect https://www.patternfly.org/components/forms/form-select}
  *
  * @param {object} props
- * @param {Array<import(~/clients/storage).Volume>} props.volumes - a collection of storage volumes
+ * @param {Array<Volume>} props.volumes - a collection of storage volumes
  * @param {object} props.formSelectProps - @see {@link https://www.patternfly.org/components/forms/form-select#props}
  * @returns {ReactComponent}
  */
@@ -88,7 +92,7 @@ const BTRFS_WITH_SNAPSHOTS = "BtrfsWithSnapshots";
  * Possible file system type options for a volume.
  * @function
  *
- * @param {import(~/clients/storage).Volume} volume
+ * @param {Volume} volume
  * @returns {string[]}
  */
 const fsOptions = (volume) => {
@@ -184,7 +188,7 @@ const FsSelectOption = ({ fsOption }) => {
  * @param {object} props
  * @param {string} props.id - Widget id.
  * @param {FsValue} props.value - Currently selected file system properties.
- * @param {import(~/clients/storage).Volume} volume - The selected storage volume.
+ * @param {Volume} volume - The selected storage volume.
  * @param {onChangeFn} props.onChange - Callback for notifying input changes.
  *
  * @returns {ReactComponent}
@@ -245,7 +249,7 @@ const FsSelect = ({ id, value, volume, onChange }) => {
  *
  * @param {object} props
  * @param {FsValue} props.value - Currently selected file system properties.
- * @param {import(~/clients/storage).Volume} volume - The selected storage volume.
+ * @param {Volume} volume - The selected storage volume.
  * @param {onChangeFn} props.onChange - Callback for notifying input changes.
  *
  * @typedef {object} FsValue
@@ -303,7 +307,7 @@ const FsField = ({ value, volume, onChange }) => {
  * @component
  *
  * @param {object} props
- * @param {import(~/clients/storage).Volume} volume - a storage volume object
+ * @param {Volume} volume - a storage volume object
  * @returns {ReactComponent}
  */
 const SizeAuto = ({ volume }) => {
@@ -490,7 +494,7 @@ const SIZE_OPTION_LABELS = Object.freeze({
  * @param {object} props
  * @param {object} props.errors - the form errors
  * @param {object} props.formData - the form data
- * @param {import(~/clients/storage).Volume} volume - the selected storage volume
+ * @param {Volume} volume - the selected storage volume
  * @param {onChangeFn} props.onChange - callback for notifying input changes
  *
  * @returns {ReactComponent}
@@ -537,7 +541,7 @@ const SizeOptions = ({ errors, formData, volume, onChange }) => {
 /**
  * Creates a new storage volume object based on given params
  *
- * @param {import(~/clients/storage).Volume} volume - a storage volume
+ * @param {Volume} volume - a storage volume
  * @param {object} formData - data used to calculate the volume updates
  * @returns {object} storage volume object
  */
@@ -567,7 +571,7 @@ const createUpdatedVolume = (volume, formData) => {
 /**
  * Form-related helper for guessing the size method for given volume
  *
- * @param {import(~/clients/storage).Volume} volume - a storage volume
+ * @param {Volume} volume - a storage volume
  * @return {string} corresponding size method
  */
 const sizeMethodFor = (volume) => {
@@ -585,7 +589,7 @@ const sizeMethodFor = (volume) => {
 /**
  * Form-related helper for preparing data based on given volume
  *
- * @param {import(~/clients/storage).Volume} volume - a storage volume object
+ * @param {Volume} volume - a storage volume object
  * @return {object} an object ready to be used as a "form state"
  */
 const prepareFormData = (volume) => {
@@ -609,7 +613,7 @@ const prepareFormData = (volume) => {
 /**
  * Initializer function for the React#useReducer used in the {@link VolumesForm}
  *
- * @param {import(~/clients/storage).Volume} volume - a storage volume object
+ * @param {Volume} volume - a storage volume object
  * @returns {object} a ready to use initial state
  */
 const createInitialState = (volume) => {
@@ -662,11 +666,11 @@ const reducer = (state, action) => {
  *
  * @param {object} props
  * @param {string} props.id - Form ID
- * @param {Array<import(~/clients/storage).Volume>} props.volumes - a collection of storage volumes
+ * @param {Array<Volume>} props.volumes - a collection of storage volumes
  * @param {onSubmitFn} props.onSubmit - Function to use for submitting a new volume
  *
  * @callback onSubmitFn
- * @param {import(~/clients/storage).Volume} volume - a storage volume object
+ * @param {Volume} volume - a storage volume object
  * @return {void}
  */
 export default function VolumeForm({ id, volume: currentVolume, templates = [], onSubmit }) {

diff --git a/web/src/components/storage/device-utils.jsx b/web/src/components/storage/device-utils.jsx
@@ -29,7 +29,7 @@ import { If } from "~/components/core";
 import { deviceSize } from "~/components/storage/utils";
 
 /**
- * @typedef {import ("~/clients/storage").StorageDevice} StorageDevice
+ * @typedef {import ("~/client/storage").DeviceManager.StorageDevice} StorageDevice
  */
 
 const ListBox = ({ children, ...props }) => <ul data-type="agama/list" data-of="agama/storage-devices" {...props}>{children}</ul>;

diff --git a/web/src/context/l10n.jsx b/web/src/context/l10n.jsx
@@ -24,9 +24,9 @@ import { useCancellablePromise } from "~/utils";
 import { useInstallerClient } from "./installer";
 
 /**
- * @typedef {import ("~/clients/l10n").Locale} Locale
- * @typedef {import ("~/clients/l10n").Keymap} Keymap
- * @typedef {import ("~/clients/l10n").Timezone} Timezone
+ * @typedef {import ("~/client/l10n").Locale} Locale
+ * @typedef {import ("~/client/l10n").Keymap} Keymap
+ * @typedef {import ("~/client/l10n").Timezone} Timezone
  */
 
 const L10nContext = React.createContext({});

diff --git a/web/src/context/product.jsx b/web/src/context/product.jsx
@@ -24,8 +24,8 @@ import { useCancellablePromise } from "~/utils";
 import { useInstallerClient } from "./installer";
 
 /**
- * @typedef {import ("~/clients/software").Product} Product
- * @typedef {import ("~/clients/software").Registration} Registration
+ * @typedef {import ("~/client/software").Product} Product
+ * @typedef {import ("~/client/software").Registration} Registration
  */
 
 const ProductContext = React.createContext([]);

diff --git a/web/tsconfig.json b/web/tsconfig.json
@@ -9,15 +9,18 @@
     "jsx": "react",
     "allowSyntheticDefaultImports": true,
     "paths": {
-      "~/*": ["src/*"],
-      "~/client": ["src/client/index.js"],
-      "@icons/*": ["node_modules/@material-symbols/svg-400/outlined/*"]
+      "~/*": [
+        "src/*"
+      ],
+      "~/client": [
+        "src/client/index.js"
+      ],
+      "@icons/*": [
+        "node_modules/@material-symbols/svg-400/outlined/*"
+      ]
     }
   },
   "include": [
     "src"
-  ],
-  "typedocOptions": {
-    "out": "jsdoc.out"
-  }
+  ]
 }