-
Notifications
You must be signed in to change notification settings - Fork 592
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(api-reference): add typedoc plugins for api reference (#1694)
* docs: add typedoc plugins and customizations * docs: support generating typedoc for all packages * docs: consolidate client doc generator plugins * docs: add core packages doc plugin * feat(client-documentation-generator): refactor plugins * chore(core-packages-documentation-generator): generate core packages doc * fix: apply review feedbacks Co-authored-by: Trivikram Kamat <[email protected]>
- Loading branch information
1 parent
96f61bb
commit 2cb016f
Showing
16 changed files
with
485 additions
and
137 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,20 +1,20 @@ | ||
| import { PluginHost } from "typedoc/dist/lib/utils"; | ||
|
|
||
| import { SdkClientRenameGlobalPlugin } from "./sdk-client-rename-global"; | ||
| import { SdkClientSourceUpdatePlugin } from "./sdk-client-source-update"; | ||
| import { SdkClientCommentUpdatePlugin } from "./sdk-client-comment-update"; | ||
| import { SdkClientRenameProjectPlugin } from "./sdk-client-rename-project"; | ||
| import { SdkClientTocPlugin } from "./sdk-client-toc-plugin"; | ||
|
|
||
| /** | ||
| * | ||
| * @param pluginHost An instance of PluginHost. | ||
| */ | ||
| module.exports = function load(pluginHost: PluginHost) { | ||
| const application = pluginHost.owner; | ||
|
|
||
| // Add renderer plugins | ||
| application.renderer.addComponent("SdkClientTocPlugin", SdkClientTocPlugin as any); | ||
| application.renderer.addComponent("SdkClientRenameGlobalPlugin", SdkClientRenameGlobalPlugin as any); | ||
| application.converter.addComponent( | ||
| "SdkClientCommentUpdatePlugin", | ||
| new SdkClientCommentUpdatePlugin(application.converter) | ||
| ); | ||
|
|
||
| // Add converter plugins | ||
| application.converter.addComponent("SdkClientSourceUpdatePlugin", SdkClientSourceUpdatePlugin as any); | ||
| application.renderer.addComponent("SdkClientTocPlugin", new SdkClientTocPlugin(application.renderer)); | ||
| application.renderer.addComponent( | ||
| "SdkClientRenameProjectPlugin", | ||
| new SdkClientRenameProjectPlugin(application.renderer) | ||
| ); | ||
| }; |
38 changes: 38 additions & 0 deletions
38
packages/client-documentation-generator/src/sdk-client-comment-update.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| import { Converter } from "typedoc/dist/lib/converter"; | ||
| import { Component, ConverterComponent } from "typedoc/dist/lib/converter/components"; | ||
| import { Context } from "typedoc/dist/lib/converter/context"; | ||
| import { getRawComment, parseComment } from "typedoc/dist/lib/converter/factories/comment"; | ||
| import { Reflection } from "typedoc/dist/lib/models/reflections"; | ||
| import ts from "typescript"; | ||
|
|
||
| /** | ||
| * Best effort make the service docs markdown looks better. | ||
| */ | ||
| @Component({ name: "SdkClientCommentUpdatePlugin" }) | ||
| export class SdkClientCommentUpdatePlugin extends ConverterComponent { | ||
| initialize() { | ||
| this.listenTo(this.owner, { | ||
| [Converter.EVENT_CREATE_DECLARATION]: this.onDeclaration, | ||
| }); | ||
| } | ||
|
|
||
| private onDeclaration(context: Context, reflection: Reflection, node?: ts.Node) { | ||
| if (!node) return; | ||
| const rawComment = getRawComment(node); | ||
| if (!rawComment) return; | ||
| const comment = parseComment(this.cleanEmptyCommentLines(rawComment)); | ||
| reflection.comment = comment; | ||
| } | ||
|
|
||
| /** | ||
| * Update documentation block to exclude empty lines. | ||
| */ | ||
| private cleanEmptyCommentLines(comment: string): string { | ||
| return comment.startsWith("/*") && comment.endsWith("*/") | ||
| ? comment | ||
| .split("\n") | ||
| .filter((line) => line.substr(line.indexOf("*") + 1).trim().length !== 0) | ||
| .join("\n") | ||
| : comment; | ||
| } | ||
| } |
27 changes: 0 additions & 27 deletions
27
packages/client-documentation-generator/src/sdk-client-rename-global.ts
This file was deleted.
Oops, something went wrong.
23 changes: 23 additions & 0 deletions
23
packages/client-documentation-generator/src/sdk-client-rename-project.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| import { readFileSync } from "fs"; | ||
| import { Component, RendererComponent } from "typedoc/dist/lib/output/components"; | ||
| import { RendererEvent } from "typedoc/dist/lib/output/events"; | ||
|
|
||
| /** | ||
| * Correct the package name in the navigator. | ||
| */ | ||
| @Component({ name: "SdkClientRenameProject" }) | ||
| export class SdkClientRenameProjectPlugin extends RendererComponent { | ||
| initialize() { | ||
| this.listenTo(this.owner, { | ||
| [RendererEvent.BEGIN]: this.onRenderedBegin, | ||
| }); | ||
| } | ||
|
|
||
| onRenderedBegin(event: RendererEvent) { | ||
| const { fullFileName } = event.project.files.filter((sourceFile) => | ||
| sourceFile.fileName.endsWith("/package.json") | ||
| )[0]; | ||
| const { name } = JSON.parse(readFileSync(fullFileName).toString()); | ||
| event.project.name = name; | ||
| } | ||
| } |
40 changes: 0 additions & 40 deletions
40
packages/client-documentation-generator/src/sdk-client-source-update.ts
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.