docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc #9293

JoshuaKGoldberg · 2024-06-06T13:12:42Z

PR Checklist

Addresses an existing open issue: fixes Documentation for AST node types #2726; fixes Docs: Add generated documentation on packages exports to the site #9298
That issue was marked as accepting prs
Steps in Contributing were taken

Overview

Sets up https://typedoc-plugin-markdown.org/plugins/docusaurus to auto-generate TypeDoc docs from packages/type-utils/src/index.ts into docs/package/type-utils/api.

💖

typescript-eslint · 2024-06-06T13:12:44Z

Thanks for the PR, @JoshuaKGoldberg!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint.

netlify · 2024-06-06T13:12:58Z

✅ Deploy Preview for typescript-eslint ready!

Name	Link
🔨 Latest commit	`e73bc3f`
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/66a795a5d6b3e50008e99508
😎 Deploy Preview	https://deploy-preview-9293--typescript-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 98 (🔴 down 1 from production) Accessibility: 100 (no change from production) Best Practices: 92 (no change from production) SEO: 90 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

nx-cloud · 2024-06-06T13:13:56Z

☁️ Nx Cloud Report

CI is running/has finished running commands for commit e73bc3f. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

✅ Successfully ran 30 targets

Sent with 💌 from NxCloud.

JoshuaKGoldberg · 2024-06-07T10:45:35Z

packages/ast-spec/src/ast-node-types.ts

-   * TS-prefixed nodes
-   */
+
+  // TS_prefixed nodes


The /** ... */ JSDoc style comment was getting picked up as a comment on specifically TSAbstractAccessorProperty.

JoshuaKGoldberg · 2024-06-07T11:10:49Z

packages/ast-spec/src/declaration/TSEnumDeclaration/spec.ts

@@ -8,14 +8,14 @@ export interface TSEnumDeclaration extends BaseNode {
  /**
   * Whether this is a `const` enum.
   * ```
-   * const enum Foo {...}
+   * const enum Foo {}


Invalid TS syntax in ```s -with or without @example or the `ts` block- causes a parse error in the generated `index.md`:

Error: MDX compilation failed for file "/Users/josh/repos/typescript-eslint/docs/packages/ast-spec/generated/index.md" Cause: Could not parse expression with acorn Details: { "cause": { "pos": 65758, "loc": { "line": 2505, "column": 102 }, "raisedAt": 3 }, "column": 103, "message": "Could not parse expression with acorn", "line": 2505, "name": "2505:103", "place": { "line": 2505, "column": 103, "offset": 65758 }, "reason": "Could not parse expression with acorn", "ruleId": "acorn", "source": "micromark-extension-mdx-expression", "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn" }

The Markdown in question:

#### Properties | Property | Type | Description | Overrides | | :------ | :------ | :------ | :------ | | `const` | `boolean` | Whether this is a `const` enum.**Example**<code>const enum Foo {...}</code> | - | | `declare` | `boolean` | Whether this is a `declare`d enum.**Example**<code>declare enum Foo {...}</code> | - | | `id` | [`Identifier`](index.md#identifier) | The enum name. | - | | `members` | [`TSEnumMember`](index.md#tsenummember)[] | The enum members. | - | | `type` | `TSEnumDeclaration` | - | [`BaseNode`](index.md#basenode).`type` | ***

...where the issue is on the <code> in the first tbody row.

JoshuaKGoldberg · 2024-06-07T11:12:49Z

packages/ast-spec/src/base/NodeOrTokenData.ts

   */
  loc: SourceLocation;

-  /**
-   * @see {Range}
-   */


These @sees just restate the type. No useful info added.

JoshuaKGoldberg · 2024-06-07T11:31:44Z

packages/ast-spec/src/declaration/ExportAllDeclaration/spec.ts

-   * export * from 'mod' assert { type: 'json' };
+   * @example
+   * ```ts
+   * export * from 'mod' assert \{ type: 'json' \};


Without these \s, Acorn give a parse error on the generated index.md:

Error: MDX compilation failed for file "/Users/josh/repos/typescript-eslint/docs/packages/ast-spec/generated/index.md" Cause: Could not parse expression with acorn Details: { "cause": { "pos": 26627, "loc": { "line": 871, "column": 174 } }, "column": 175, "message": "Could not parse expression with acorn", "line": 871, "name": "871:175", "place": { "line": 871, "column": 175, "offset": 26627 }, "reason": "Could not parse expression with acorn", "ruleId": "acorn", "source": "micromark-extension-mdx-expression", "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn" }

The Markdown in question:

#### Properties | Property | Type | Description | Overrides | | :------ | :------ | :------ | :------ | | ~~`assertions`~~ | [`ImportAttribute`](index.md#importattribute)[] | The assertions declared for the export.**Example**<code>export * from 'mod' assert { type: 'json' };</code>**Deprecated**-- Replaced with `attributes`. | - | | `attributes` | [`ImportAttribute`](index.md#importattribute)[] | The attributes declared for the export.**Example**<code>export * from 'mod' assert { type: 'json' };</code> | - | | `exportKind` | `ExportAndImportKind` | The kind of the export. | - | | `exported` | `null` \| [`Identifier`](index.md#identifier) | The name for the exported items. `null` if no name is assigned. | - | | `source` | [`StringLiteral`](index.md#stringliteral) | The source module being exported from. | - | | `type` | `ExportAllDeclaration` | - | [`BaseNode`](index.md#basenode).`type` | ***

...where the issue is on the <code> in the first tbody row.

JoshuaKGoldberg · 2024-06-07T12:43:08Z

packages/ast-spec/src/declaration/VariableDeclaration/spec.ts

@@ -11,7 +11,8 @@ export interface LetOrConstOrVarDeclaration extends BaseNode {
  /**
   * The variables declared by this declaration.
   * Note that there may be 0 declarations (i.e. `const;`).
-   * ```
+   * @example
+   * ```ts


I tried to make sure all ```s had a language and were in a proper @example, so they'd play nicely with docs generation. But multiline ones expose a bug in the markdown table output 🫤:

Resolved by splitting into individual @examples. 🤷

Some of them are still a little messy... but I don't know the right way to get around this. 😬 putting in review.

bradzacher

https://deploy-preview-9293--typescript-eslint.netlify.app/packages/utils/generated/namespaces/ASTUtils/

Bug: This page loses the sidebar (and is not listed in the sidebar at all).

Question: can we change the TOC so that we show one fewer level of headings on these pages? It's pretty low value showing the Parameters, Returns etc headings in the TOC -- i'd say it's even just noisy / confusing.

JoshuaKGoldberg · 2024-06-25T05:52:18Z

Yeah @bradzacher that makes sense. I was excited about getting the utils package in there but it's a bit more complicated and I think we'll need to look more critically at its docs.

The presence of multiple / nested namespaces makes the doc gen trickier. I tried much of https://typedoc-plugin-markdown.org/docs/options/file-options but couldn't figure out how to collapse it all into one page.

For now, I just removed utils from the array of generated package docs.

packages/ast-spec/src/element/TSEnumMember/spec.ts

Josh-Cena · 2024-07-20T20:09:38Z

packages/ast-spec/src/declaration/VariableDeclaration/spec.ts

   * declare const x = 1;
   * ```
   */
  declare: boolean;
  /**
   * The keyword used to declare the variable(s)
   * ```
+   * @example


Same here: not sure why we want to split them up (and I think there's a stray ``` above)

codecov · 2024-07-20T20:26:07Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.45%. Comparing base (6b92aa5) to head (e73bc3f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9293   +/-   ##
=======================================
  Coverage   88.45%   88.45%           
=======================================
  Files         422      422           
  Lines       14695    14695           
  Branches     4298     4298           
=======================================
  Hits        12998    12998           
  Misses       1372     1372           
  Partials      325      325

Flag	Coverage Δ
unittest	`88.45% <ø> (ø)`

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

Files	Coverage Δ
...eslint-plugin/src/rules/consistent-type-imports.ts	`94.77% <ø> (ø)`
packages/utils/src/ts-eslint/RuleTester.ts	`50.00% <ø> (ø)`
packages/utils/src/ts-eslint/SourceCode.ts	`50.00% <ø> (ø)`

JoshuaKGoldberg · 2024-07-29T15:58:11Z

Merging after talking privately & confirming that:

The docs here are so big that it's super hard to actually review
This is generally good to go otherwise

docs: add type-utils docs with docusaurus-plugin-typedoc

1ea3573

Well, it works now

9b6b2e2

JoshuaKGoldberg mentioned this pull request Jun 6, 2024

docs: add minimal docs page for type-utils package #9294

Merged

3 tasks

JoshuaKGoldberg added 4 commits June 6, 2024 13:38

Wow, single page actually works well

0924498

Add back comment

584df32

chore: update knip.ts

d0c8ce7

Add ast-spec underneath typescript-estree

0db3d52

JoshuaKGoldberg changed the title ~~docs: add type-utils docs with docusaurus-plugin-typedoc~~ docs: add ast-spec, type-utils, utils docs with docusaurus-plugin-typedoc Jun 7, 2024

Internal ast-spec cleanups

f958009

JoshuaKGoldberg mentioned this pull request Jun 7, 2024

Support for configuring no inherit class names via a config file rather than comment tag jonchardy/typedoc-plugin-no-inherit#34

Open

JoshuaKGoldberg added 3 commits June 7, 2024 06:44

Forked typedoc-plugin-no-inherit

1698570

Undo unnecessary Linter.ts change

dda405a

Fix up some examples to be true code blocks

cf490b1

JoshuaKGoldberg commented Jun 7, 2024

View reviewed changes

fix lint for some reason

9fe7448

JoshuaKGoldberg requested a review from Josh-Cena June 7, 2024 12:45

This was referenced Jun 8, 2024

feat: added alwaysOmitInheritance option jonchardy/typedoc-plugin-no-inherit#35

Closed

Docs: Add generated documentation on packages exports to the site #9298

Closed

JoshuaKGoldberg added 2 commits June 22, 2024 13:08

Split up variable multiline examples

3021816

Merge branch 'main'

7185b7e

JoshuaKGoldberg marked this pull request as ready for review June 22, 2024 20:16

bradzacher reviewed Jun 23, 2024

View reviewed changes

JoshuaKGoldberg added 2 commits June 25, 2024 01:52

Remove utils TypeDoc generation

15c0870

Merge branch 'main'

258419e

JoshuaKGoldberg requested a review from bradzacher June 25, 2024 06:07

JoshuaKGoldberg changed the title ~~docs: add ast-spec, type-utils, utils docs with docusaurus-plugin-typedoc~~ docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc Jun 25, 2024

Josh-Cena reviewed Jul 18, 2024

View reviewed changes

packages/ast-spec/src/element/TSEnumMember/spec.ts Show resolved Hide resolved

one example

fa89b9e

Josh-Cena reviewed Jul 20, 2024

View reviewed changes

JoshuaKGoldberg added 3 commits July 29, 2024 09:12

Merge branch 'main' into docusaurus-plugin-typedoc

0e8f79d

Fixed remaining example tags

dd17e7a

Fixed remaining example tags

e73bc3f

JoshuaKGoldberg merged commit 9927a29 into typescript-eslint:main Jul 29, 2024
60 checks passed

JoshuaKGoldberg deleted the docusaurus-plugin-typedoc branch July 29, 2024 15:58

github-actions bot locked as resolved and limited conversation to collaborators Aug 7, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc #9293

docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc #9293

JoshuaKGoldberg commented Jun 6, 2024 •

edited

Loading

typescript-eslint bot commented Jun 6, 2024

netlify bot commented Jun 6, 2024 •

edited

Loading

nx-cloud bot commented Jun 6, 2024 •

edited

Loading

JoshuaKGoldberg Jun 7, 2024

JoshuaKGoldberg Jun 7, 2024

JoshuaKGoldberg Jun 7, 2024

JoshuaKGoldberg Jun 7, 2024

JoshuaKGoldberg Jun 7, 2024

JoshuaKGoldberg Jun 22, 2024

JoshuaKGoldberg Jun 22, 2024

bradzacher left a comment

JoshuaKGoldberg commented Jun 25, 2024

Josh-Cena Jul 20, 2024

codecov bot commented Jul 20, 2024 •

edited

Loading

JoshuaKGoldberg commented Jul 29, 2024

docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc #9293

docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc #9293

Conversation

JoshuaKGoldberg commented Jun 6, 2024 • edited Loading

PR Checklist

Overview

typescript-eslint bot commented Jun 6, 2024

netlify bot commented Jun 6, 2024 • edited Loading

✅ Deploy Preview for typescript-eslint ready!

nx-cloud bot commented Jun 6, 2024 • edited Loading

☁️ Nx Cloud Report

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

bradzacher left a comment

Choose a reason for hiding this comment

JoshuaKGoldberg commented Jun 25, 2024

Choose a reason for hiding this comment

codecov bot commented Jul 20, 2024 • edited Loading

Codecov Report

JoshuaKGoldberg commented Jul 29, 2024

JoshuaKGoldberg commented Jun 6, 2024 •

edited

Loading

netlify bot commented Jun 6, 2024 •

edited

Loading

nx-cloud bot commented Jun 6, 2024 •

edited

Loading

codecov bot commented Jul 20, 2024 •

edited

Loading