docs: autogenerated typedoc reference (#2308)

Author: lukegalbraithrussell

.github/maintainers_guide.md

@@ -29,7 +29,9 @@ We have included `launch.json` files that store configuration for `vscode` debug
 
 See the [Docs README](https://github.com/slackapi/node-slack-sdk/blob/main/docs/README.md) for information on how the docs site work. 
 
-The reference docs are generated on every site build, pulling from this repo's files. The site is built automatically on every release via `docs-deploy.yml`. 
+The reference docs for each package is independent of the others. They're generated using `typedoc` and `typedoc-plugin-markdown`. In each package's `package.json` there's a `docs` command that generates reference docs for that package based on the configuration settings found in `/package-name/typedoc.json`. 
+
+The script places the reference markdown files in `/reference/package-name`.
 
 ### 🚀 Releases
 _For beta releases, see [**Beta Releases**](https://github.com/slackapi/node-slack-sdk/blob/main/.github/maintainers_guide.md#-beta-releases) section below_
@@ -50,38 +52,40 @@ Releasing can feel intimidating at first, but rest assured: if you make a mistak
 
 4. For each package to be released, run `npm run test` to verify that tests are passing and code is free of linting errors.
 
-5. On your new branch, bump the version(s) in `package.json` (see [Versioning and Tags](https://github.com/slackapi/node-slack-sdk/blob/main/.github/maintainers_guide.md#-versioning-and-tags))
+5. Generate the reference docs for that package by running `npm run docs`.
+
+6. On your new branch, bump the version(s) in `package.json` (see [Versioning and Tags](https://github.com/slackapi/node-slack-sdk/blob/main/.github/maintainers_guide.md#-versioning-and-tags))
 
     - Make a single commit for the version(s) bump, following the format in: ([Example](https://github.com/slackapi/node-slack-sdk/commit/1503609d79abf035e9e21bad7360e124e4211594))
 
     - Create a pull request for the version change ([Example](https://github.com/slackapi/node-slack-sdk/pull/1059))
 
     - Add appropriate labels on the PR, including `release`
 
-6. Once the PR has been approved and tests have passed, merge it into the main repository.
+7. Once the PR has been approved and tests have passed, merge it into the main repository.
 
     -  Check out your local `main` branch and update it to get the latest changes: `git checkout main && git pull origin main`
 
     -  Add a version tag (ie, `git tag @slack/[email protected]`)
 
     -  Push the new tag up to origin: `git push --tags origin`
 
-7. Publish the release to npm
+8. Publish the release to npm
     - To publish, you need to be a member of the `slack Org` on npm and set up 2-Factor Auth with your passsword generator of choice. Before you can publish with npm, you must run `npm login` from the command line.
 
     - As the final validation, within the package directory (ex: `packages/types`), run `mv package-lock.json package-lock.json.bk && rm -rf node_modules/ dist/ && npm i && npm test && npm pack` and confirm if there are `*.js`, `*.d.ts` files under the `dist` directory.
 
     - Run `npm publish . --otp YOUR_OTP_CODE`. To generate an OTP (One Time Password), use your password generator of choice (Duo, 1Password)
 
-8. Close GitHub Milestone(s)
+9. Close GitHub Milestone(s)
 
     - Close the relevant GitHub Milestone(s) for the release(s)
 
     - Check the existing GitHub Milestones to see if the next minor version exists. If it doesn't, then create a GitHub Milestone for new issues to live in. Typically, you'll create a new minor version - however, if there are any bugs that need to be carried over from the current GitHub Milestone, you could make a Milestone for a patch version to reflect those issues
 
     - Move any unfinished, open issues to the next GitHub Milestone
 
-9. Create GitHub Release(s) with release notes
+10. Create GitHub Release(s) with release notes
 
     - From the repository, navigate to the **Releases** section and draft a new release
 
@@ -93,7 +97,7 @@ Releasing can feel intimidating at first, but rest assured: if you make a mistak
 
     - Once the release notes are ready, click the "Publish Release" button to make them public
 
-10. Communicate the release (as appropriate)
+11. Communicate the release (as appropriate)
 
     - **Internal**
 

docs/docusaurus.config.js

@@ -44,7 +44,6 @@ const config = {
 
   plugins: [
     'docusaurus-theme-github-codeblock',
-
     [
       '@docusaurus/plugin-client-redirects',
       {
@@ -53,107 +52,13 @@ const config = {
             to: '/getting-started#getting-a-token-to-use-the-web-api',
             from: ['/auth'],
           },
-          {
-            to: '/reference/logger',
-            from: ['/reference'],
-          },
           {
             to: 'https://github.com/SlackAPI/node-slack-sdk/releases',
             from: ['/changelog'],
           },
         ],
       },
     ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'cli-test',
-        entryPoints: ['../packages/cli-test/src/index.ts'],
-        tsconfig: '../packages/cli-test/tsconfig.json',
-        out: './content/reference/cli-test',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'events-api',
-        entryPoints: ['../packages/events-api/src/index.ts'],
-        tsconfig: '../packages/events-api/tsconfig.json',
-        out: './content/reference/events-api',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'interactive-messages',
-        entryPoints: ['../packages/interactive-messages/src/index.ts'],
-        tsconfig: '../packages/interactive-messages/tsconfig.json',
-        out: './content/reference/interactive-messages',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'logger',
-        entryPoints: ['../packages/logger/src/index.ts'],
-        tsconfig: '../packages/logger/tsconfig.json',
-        out: './content/reference/logger',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'oauth',
-        entryPoints: ['../packages/oauth/src/index.ts'],
-        tsconfig: '../packages/oauth/tsconfig.json',
-        out: './content/reference/oauth',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'rtm-api',
-        entryPoints: ['../packages/rtm-api/src/index.ts'],
-        tsconfig: '../packages/rtm-api/tsconfig.json',
-        out: './content/reference/rtm-api',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'socket-mode',
-        entryPoints: ['../packages/socket-mode/src/index.ts'],
-        tsconfig: '../packages/socket-mode/tsconfig.json',
-        out: './content/reference/socket-mode',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'types',
-        entryPoints: ['../packages/types/src/index.ts'],
-        tsconfig: '../packages/types/tsconfig.json',
-        out: './content/reference/types',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'web',
-        entryPoints: ['../packages/web-api/src/index.ts'],
-        tsconfig: '../packages/web-api/tsconfig.json',
-        out: './content/reference/web-api',
-      },
-    ],
-    [
-      'docusaurus-plugin-typedoc',
-      {
-        id: 'webhook',
-        entryPoints: ['../packages/webhook/src/index.ts'],
-        tsconfig: '../packages/webhook/tsconfig.json',
-        out: './content/reference/webhook',
-      },
-    ],
   ],
 
   themeConfig:

docs/sidebars.js

@@ -63,98 +63,16 @@ const sidebars = {
     {
       type: 'category',
       label: 'Reference',
+      link: {
+        type: 'generated-index',
+        slug: '/reference',
+      },
       items: [
-        {
-          type: 'category',
-          label: '@slack/cli-test',
-          link: {
-            type: 'doc',
-            id: 'reference/cli-test/index',
-          },
-          items: require('./content/reference/cli-test/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/events-api',
-          link: {
-            type: 'doc',
-            id: 'reference/events-api/index',
-          },
-          items: require('./content/reference/events-api/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/interactive-messages',
-          link: {
-            type: 'doc',
-            id: 'reference/interactive-messages/index',
-          },
-          items: require('./content/reference/interactive-messages/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/logger',
-          link: {
-            type: 'doc',
-            id: 'reference/logger/index',
-          },
-          items: require('./content/reference/logger/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/oauth',
-          link: {
-            type: 'doc',
-            id: 'reference/oauth/index',
-          },
-          items: require('./content/reference/oauth/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/rtm-api',
-          link: {
-            type: 'doc',
-            id: 'reference/rtm-api/index',
-          },
-          items: require('./content/reference/rtm-api/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/socket-mode',
-          link: {
-            type: 'doc',
-            id: 'reference/socket-mode/index',
-          },
-          items: require('./content/reference/socket-mode/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/types',
-          link: {
-            type: 'doc',
-            id: 'reference/types/index',
-          },
-          items: require('./content/reference/types/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/web-api',
-          link: {
-            type: 'doc',
-            id: 'reference/web-api/index',
-          },
-          items: require('./content/reference/web-api/typedoc-sidebar.cjs'),
-        },
-        {
-          type: 'category',
-          label: '@slack/webhook',
-          link: {
-            type: 'doc',
-            id: 'reference/webhook/index',
-          },
-          items: require('./content/reference/webhook/typedoc-sidebar.cjs'),
-        },
-      ],
+      {
+        type: 'autogenerated',
+        dirName: 'reference',
+      },
+    ]
     },
     {type: 'html', value: '<hr>'},
     'support-schedule',

docs/typedoc.json

@@ -27,6 +27,7 @@
   "scripts": {
     "build": "npm run build:clean && tsc",
     "build:clean": "shx rm -rf ./dist ./coverage",
+    "docs": "npx typedoc --plugin typedoc-plugin-markdown",
     "lint": "npx @biomejs/biome check .",
     "lint:fix": "npx @biomejs/biome check --write .",
     "prepare": "npm run build",
@@ -53,6 +54,8 @@
     "shx": "^0.4.0",
     "sinon": "^21.0.0",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.28.7",
+    "typedoc-plugin-markdown": "^4.7.1",
     "typescript": "5.8.3"
   }
 }

packages/cli-test/package.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "plugin": ["typedoc-plugin-markdown"],
+  "outputs": [
+    {
+      "name": "markdown",
+      "path": "../../docs/content/reference/cli-test"
+    }
+  ],
+  "skipErrorChecking": true,
+  "useCodeBlocks": true,
+  "logLevel": "Error",
+  "readme": "none",
+  "gitRevision": "main",
+  "includeVersion": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "hideGenerator": true,
+  "jsDocCompatibility": true,
+  "hidePageHeader": true,
+  "entryFileName": "index",
+  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/*.test-d.ts"]
+}

packages/cli-test/typedoc.json

@@ -29,6 +29,7 @@
     "prepare": "npm run build",
     "build": "npm run build:clean && tsc",
     "build:clean": "shx rm -rf ./dist ./coverage",
+    "docs": "npx typedoc --plugin typedoc-plugin-markdown",
     "lint": "npx @biomejs/biome check .",
     "lint:fix": "npx @biomejs/biome check --write .",
     "mocha": "mocha --config ./test/.mocharc.json src/*.spec.js",
@@ -52,6 +53,8 @@
     "sinon": "^21.0.0",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.28.7",
+    "typedoc-plugin-markdown": "^4.7.1",
     "typescript": "^5.5.4"
   }
 }

packages/logger/package.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["src/index.ts"],
+  "plugin": ["typedoc-plugin-markdown"],
+  "outputs": [
+    {
+      "name": "markdown",
+      "path": "../../docs/content/reference/logger"
+    }
+  ],
+  "skipErrorChecking": true,
+  "useCodeBlocks": true,
+  "logLevel": "Error",
+  "readme": "none",
+  "gitRevision": "main",
+  "includeVersion": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "hideGenerator": true,
+  "jsDocCompatibility": true,
+  "hidePageHeader": true,
+  "entryFileName": "index",
+  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/*.test-d.ts"]
+}