Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork2.8k
docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc#9293
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
docs: add ast-spec, type-utils docs with docusaurus-plugin-typedoc#9293
Uh oh!
There was an error while loading.Please reload this page.
Conversation
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 onhttps://opencollective.com/typescript-eslint. |
netlifybot commentedJun 6, 2024 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
✅ Deploy Preview fortypescript-eslint ready!
To edit notification comments on pull requests, go to yourNetlify site configuration. |
nx-cloudbot commentedJun 6, 2024 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
| * TS-prefixed nodes | ||
| */ | ||
| // TS_prefixed nodes |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
The/** ... */ JSDoc style comment was getting picked up as a comment on specificallyTSAbstractAccessorProperty.
| @@ -8,14 +8,14 @@ export interface TSEnumDeclaration extends BaseNode { | |||
| /** | |||
| * Whether this is a `const` enum. | |||
| * ``` | |||
| * const enum Foo {...} | |||
| * const enum Foo {} | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 acornDetails:{ "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`| <p>Whether this is a`const` enum.</p><p>**Example**</p><code>const enum Foo {...}</code>| -||`declare`|`boolean`| <p>Whether this is a`declare`d enum.</p><p>**Example**</p><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.
| */ | ||
| loc: SourceLocation; | ||
| /** | ||
| * @see {Range} | ||
| */ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
These@sees just restate the type. No useful info added.
| * export * from 'mod' assert { type: 'json' }; | ||
| * @example | ||
| * ```ts | ||
| * export * from 'mod' assert \{ type: 'json' \}; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Without these\s, Acorn give a parse error on the generatedindex.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 acornDetails:{ "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)[]| <p>The assertions declared for the export.</p><p>**Example**</p><code>export * from 'mod' assert { type: 'json' };</code><p>**Deprecated**</p><p>-- Replaced with`attributes`.</p>| -||`attributes`|[`ImportAttribute`](index.md#importattribute)[]| <p>The attributes declared for the export.</p><p>**Example**</p><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.
| @@ -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 | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 🫤:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Resolved by splitting into individual@examples. 🤷
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Some of them are still a little messy... but I don't know the right way to get around this. 😬 putting in review.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 theParameters,Returns etc headings in the TOC -- i'd say it's even just noisy / confusing.
Yeah@bradzacher that makes sense. I was excited about getting the The presence of multiple / nested namespaces makes the doc gen trickier. I tried much ofhttps://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 |
Uh oh!
There was an error while loading.Please reload this page.
| * declare const x = 1; | ||
| * ``` | ||
| */ | ||
| declare: boolean; | ||
| /** | ||
| * The keyword used to declare the variable(s) | ||
| * ``` | ||
| * @example |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Same here: not sure why we want to split them up (and I think there's a stray``` above)
codecovbot commentedJul 20, 2024 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
Codecov ReportAll modified and coverable lines are covered by tests ✅
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
Flags with carried forward coverage won't be shown.Click here to find out more.
|
Merging after talking privately & confirming that:
|
9927a29 intotypescript-eslint:mainUh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
PR Checklist
Overview
Sets uphttps://typedoc-plugin-markdown.org/plugins/docusaurus to auto-generate TypeDoc docs from
packages/type-utils/src/index.tsintodocs/package/type-utils/api.💖