docs: sprucing up docs, esp. reference doc generation #2070

filmaj · 2024-10-03T19:45:32Z

dynamically load generated sidebar items - requires a bit of gymnastics, because TypeDoc, which imports+parses TypeScript code to generate docs from source code comments, runs in parallel during docusaurus sidebar generation. As a result, sometimes there can be race-condition-like errors where the TypeDoc generation is not complete before the sidebar generation kicks off. Code was added to, basically, wait for the relevant sub-package TypeDoc routines to complete before finalizing the sidebar items.
add biome / linting to docs folder
lint during docs CI
tweak generated reference documentation styles (tables instead of lists where possible)

Doing this as part of a an initial pass to learn the docusaurus ropes as I inch towards applying the same thing to bolt-js docs.

I left some in-line comments with screenshots of relevant changes. The big visual change is using tables for API references instead of bulleted lists: I think this is more visually pleasing and also scalable as we add more content to the docs.

…o docs folder, lint during docs CI, tweak generated reference documentation styles (tables instead of lists where possible).

docs/docusaurus.config.js

filmaj · 2024-10-03T19:47:44Z

docs/docusaurus.config.js

+ */
+function packageReferenceOptions(pkg) {
+  return {
+    classPropertiesFormat: 'table',


The various *Format properties and setting them to table, I think, is nicer than the default of a bulleted list - makes better use of horizontal space, and as we add more kinds of information to our source code comments / JSdocs, these should show up as separate columns. E.g. if we add an @examples JSDoc tag to some method docs, that will show up as a new column in the generated docs.

An example of a table this setting outputs:

nice! I agree the table is the way to go 🎉

codecov · 2024-10-03T19:47:58Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.74%. Comparing base (da9100d) to head (791df25).
Report is 48 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2070   +/-   ##
=======================================
  Coverage   91.74%   91.74%           
=======================================
  Files          38       38           
  Lines       10081    10083    +2     
  Branches      631      631           
=======================================
+ Hits         9249     9251    +2     
  Misses        820      820           
  Partials       12       12

Flag	Coverage Δ
cli-hooks	`95.23% <ø> (ø)`
cli-test	`95.69% <ø> (+<0.01%)`	⬆️
oauth	`77.39% <ø> (ø)`
socket-mode	`58.22% <ø> (ø)`
web-api	`96.89% <ø> (ø)`
webhook	`96.65% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

filmaj · 2024-10-03T19:48:20Z

docs/package.json

-    "start": "docusaurus start",
-    "build": "docusaurus build",
+    "start": "TYPEDOC_WATCH=true docusaurus start",
+    "build": "TYPEDOC_WATCH=false docusaurus build",


Followed these docs to set up proper TypeScript reference doc re-generation watching: https://typedoc-plugin-markdown.org/plugins/docusaurus/watch-mode

filmaj · 2024-10-03T19:49:30Z

packages/logger/src/index.ts

@@ -9,59 +9,59 @@ export enum LogLevel {
 }

 /**
- * Interface for objects where objects in this package's logs can be sent (can be used as `logger` option).
+ * Logging interface exposing different methods to log at different {@link LogLevel}s.


By using {@link} inline tags, the generated reference documentation figures out what to link to 😍

filmaj · 2024-10-03T19:50:56Z

packages/logger/src/index.ts

@@ -94,53 +95,35 @@ export class ConsoleLogger implements Logger {
    return this.level;
  }

-  /**


We can forego the docs here because docs generation is smart enough to pull in, as a fallback, the description of this method from the Logger interface this class implements!

…docs

filmaj · 2024-10-03T20:27:14Z

Odd, docs building seems to fail in CI but runs fine for me locally 🤔 need to investigate more.

…orting them

filmaj · 2024-10-04T12:35:52Z

.github/workflows/docs-deploy.yml

@@ -31,6 +31,22 @@ jobs:
        run: npm ci
        working-directory: ./docs

+      - name: Install sub-package dependencies


Since the docs sidebar generation relies on importing and parsing TypeScript source of each sub-package we wish to document, we need to pull in the dependencies of each sub-package before building can begin.

filmaj · 2024-10-04T12:36:52Z

docs/docusaurus.config.js

@@ -32,10 +58,12 @@ const config = {
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
+          sidebarItemsGenerator: async () => {


Leveraged this documented approach here: https://typedoc-plugin-markdown.org/plugins/docusaurus/sidebar#injecting-into-autogenerated-sidebar

filmaj · 2024-10-04T12:37:25Z

docs/docusaurus.config.js

-        out: "./content/reference/webhook",
-      }
-    ]
+    ...PACKAGES.map((pkg) => ['docusaurus-plugin-typedoc', packageReferenceOptions(pkg)]),


DRYing things up here

filmaj · 2024-10-04T12:41:05Z

docs/sidebars.js

+      type: 'doc',
+      id: `reference/${pkg}/index`,
+    },
+    items: await waitAndImportFile(`./content/reference/${pkg}/typedoc-sidebar.cjs`),


One issue I saw playing around with the docs is that sometimes, as part of docs re-generation, I would get MODULE_NOT_FOUND errors where the sidebar generation was executing, and the generated typedoc files for each sub-package was missing. I think this has something to do with the docusaurus lifecycle: plugins we use, like typedoc, are still executing will docusaurus is trying to generate the sidebar. This lifecycle is a bit unclear to me. In any case, to prevent this error, I rewrote this part so that requireing the relevant sub-package's generated typedoc only happens once the generated file is actually present. It seems to have addressed the issue.

is the file pretty much guaranteed to generate within 50ms or should we increase this for flexibility?

Hard to say 😢 initially, at least when running locally, I had this set to 200 and things worked fine. After a while I decided to drop to 50 to see if that changed behaviour, but that also seems to work locally 🤷

filmaj · 2024-10-04T12:43:30Z

docs/sidebars.js

-    'packages/rtm-api',
-    'packages/webhook',
-    'packages/socket-mode',
+    { type: 'doc', id: 'getting-started' },


Moving to the more fine-control approach of providing our own asynchronous sidebar generator function, for some reason, requires the output of the function to be the more verbose list-of-objects for sidebar items - I'd get errors otherwise. So, had to move away from the the convenience string items 🤷

filmaj · 2024-10-04T12:43:46Z

docs/sidebars.js

-        },
-      ],
+      label: 'API Reference',
+      items: apiReferenceItems,


This part was also DRYed up a bit

filmaj · 2024-10-04T12:44:03Z

docs/src/css/custom.css

@@ -4,7 +4,7 @@
 * work well for content-centric websites.
 */

- :root {
+:root {


Purely linter fixes

filmaj · 2024-10-04T12:44:34Z

docs/src/theme/NotFound/Content/index.js

 import Translate from '@docusaurus/Translate';
 import Heading from '@theme/Heading';
-export default function NotFoundContent({className}) {
+import clsx from 'clsx';


Purely linter fixes

filmaj · 2024-10-04T12:44:55Z

docs/src/theme/NotFound/index.js

-import React from 'react';
-import {translate} from '@docusaurus/Translate';
-import {PageMetadata} from '@docusaurus/theme-common';
+import { translate } from '@docusaurus/Translate';


Linter fixes only here

filmaj · 2024-10-04T12:45:03Z

docs/static/img/style.css

@@ -1,20 +1,20 @@
 /* Color variables */


Linter fixes only here

hello-ashleyintech

excellent work and LGTM 😄 left a few questions, mostly for my learning purposes 🧠

hello-ashleyintech · 2024-10-04T13:42:02Z

docs/src/theme/NotFound/Content/index.js

-              If we've led you astray, please let us know. We'll do our best to get things in order. 
-
+            <Translate id="theme.NotFound.p1" description="The first paragraph of the 404 page">
+              If we've led you astray, please let us know. We'll do our best to get things in order.


this might be more of a copy nit for a follow up PR, but should we include some sort of link or CTA here so folks can leave feedback on the docs?

Great call. @hello-ashleyintech perhaps you can help me, a total React noob, here: I tried wrapping the "please let us know" text in an <a href=""></a> tag and link to this repo's issue creation, but I get a, I think, React error 😢

How.. does one do links in React? 👶

ooooh yes! That looks like it might actually be caused by embedding a link in the <Translate> tag from Docusaurus. It seems like that tag only supports simple strings. The suggested workaround in the docs is to break this into substrings wrapped in the <Translate> tag - maybe to keep that link as part of the translation it could be something like:

<Translate>If we've led you astray, </Translate><a href=""><Translate>please let us know</Translate></a><Translate>. We'll do our best to get things in order.</Translate>

If that doesn't work though then we might need to just not translate the please let us know line for now 😬

hello-ashleyintech · 2024-10-04T13:43:29Z

docs/docusaurus.config.js

+ */
+function packageReferenceOptions(pkg) {
+  return {
+    classPropertiesFormat: 'table',


nice! I agree the table is the way to go 🎉

hello-ashleyintech · 2024-10-04T13:45:52Z

docs/sidebars.js

+      type: 'doc',
+      id: `reference/${pkg}/index`,
+    },
+    items: await waitAndImportFile(`./content/reference/${pkg}/typedoc-sidebar.cjs`),


is the file pretty much guaranteed to generate within 50ms or should we increase this for flexibility?

… to speed up builds

…t rely on typedoc execution for sidebar entries.

lukegalbraithrussell · 2024-12-11T21:00:05Z

Closing for now -- we ran into build issues with this approach. I'll take another crack at this early next year

Filip Maj added 2 commits October 3, 2024 15:40

docs: dynamically load generated sidebar items, add biome / linting t…

57be346

…o docs folder, lint during docs CI, tweak generated reference documentation styles (tables instead of lists where possible).

jsdoc for refdoc generation helper function

a0e5480

filmaj added docs M-T: Documentation work only semver:patch tests M-T: Testing work only area:typescript issues that specifically impact using the package from typescript projects labels Oct 3, 2024

filmaj requested review from lukegalbraithrussell and a team October 3, 2024 19:45

filmaj self-assigned this Oct 3, 2024

filmaj commented Oct 3, 2024

View reviewed changes

docs/docusaurus.config.js Outdated Show resolved Hide resolved

filmaj commented Oct 3, 2024

View reviewed changes

docs/docusaurus.config.js Outdated Show resolved Hide resolved

filmaj commented Oct 3, 2024

View reviewed changes

Filip Maj added 3 commits October 3, 2024 16:09

more drying up of packages, install sub-package deps before building …

c9d4e42

…docs

ignore certain sub-packages when installing deps

816a689

fix up bash hackery

e436522

filmaj marked this pull request as draft October 3, 2024 20:27

Filip Maj added 2 commits October 3, 2024 17:13

try to await generated typedoc sidebar entries to be ready before imp…

ee99339

…orting them

move api reference sidebar item building into own for..of loop

e5165b8

filmaj commented Oct 4, 2024

View reviewed changes

docs/src/css/custom.css

@@ -4,7 +4,7 @@

* work well for content-centric websites.

*/

:root {

:root {

Copy link

Contributor Author

filmaj Oct 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Purely linter fixes

filmaj commented Oct 4, 2024

View reviewed changes

docs/static/img/style.css

@@ -1,20 +1,20 @@

/* Color variables */

Copy link

Contributor Author

filmaj Oct 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linter fixes only here

filmaj marked this pull request as ready for review October 4, 2024 12:48

hello-ashleyintech approved these changes Oct 4, 2024

View reviewed changes

Filip Maj added 11 commits October 4, 2024 13:15

link up to issue submission on 404 page, try using esbuild and loader…

0455e4a

… to speed up builds

fixing some broken links

80eded8

add nvmrc for each node switching to required version

d5e6077

one more broken link

c713979

try no-minify when building

fbed716

try no-minify when watching too

94edb5e

lint fix

a144b0c

log out doc building performance logging

43a0f26

testing some stuff out

807a87b

just use static sidebar links for each sub-package API reference, don…

9317139

…t rely on typedoc execution for sidebar entries.

some cleanup

791df25

filmaj mentioned this pull request Oct 15, 2024

feat(web-api): add request interceptor and HTTP adapter config to WebClient [ISSUE-2073] #2076

Merged

2 tasks

lukegalbraithrussell closed this Dec 11, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: sprucing up docs, esp. reference doc generation #2070

docs: sprucing up docs, esp. reference doc generation #2070

filmaj commented Oct 3, 2024 •

edited

Loading

filmaj Oct 3, 2024 •

edited

Loading

hello-ashleyintech Oct 4, 2024

codecov bot commented Oct 3, 2024 •

edited

Loading

filmaj Oct 3, 2024

filmaj Oct 3, 2024

filmaj Oct 3, 2024

filmaj commented Oct 3, 2024 •

edited

Loading

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

hello-ashleyintech Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

filmaj Oct 4, 2024

hello-ashleyintech left a comment

hello-ashleyintech Oct 4, 2024

filmaj Oct 4, 2024 •

edited

Loading

hello-ashleyintech Oct 4, 2024 •

edited

Loading

hello-ashleyintech Oct 4, 2024

hello-ashleyintech Oct 4, 2024

lukegalbraithrussell commented Dec 11, 2024

docs: sprucing up docs, esp. reference doc generation #2070

docs: sprucing up docs, esp. reference doc generation #2070

Conversation

filmaj commented Oct 3, 2024 • edited Loading

filmaj Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Oct 3, 2024 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

filmaj commented Oct 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hello-ashleyintech left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

filmaj Oct 4, 2024 • edited Loading

Choose a reason for hiding this comment

hello-ashleyintech Oct 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lukegalbraithrussell commented Dec 11, 2024

filmaj commented Oct 3, 2024 •

edited

Loading

filmaj Oct 3, 2024 •

edited

Loading

codecov bot commented Oct 3, 2024 •

edited

Loading

filmaj commented Oct 3, 2024 •

edited

Loading

filmaj Oct 4, 2024 •

edited

Loading

hello-ashleyintech Oct 4, 2024 •

edited

Loading