From a7c481c4001631ee592c364da1fb5a114b1c12a0 Mon Sep 17 00:00:00 2001 From: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com> Date: Thu, 31 Aug 2023 10:30:36 -0700 Subject: [PATCH] feat(api-markdown-documenter): Add api item name to document nodes (#17113) Gives consumers of the document nodes a bit more contextual information about what the document represents in terms of the API model. Useful for generating derived metadata, etc. Also makes a couple of misc. logging improvements. --- .../api-report/api-markdown-documenter.api.md | 2 ++ tools/api-markdown-documenter/package.json | 2 +- tools/api-markdown-documenter/src/RenderMarkdown.ts | 7 ++++++- .../src/api-item-transforms/TransformApiModel.ts | 4 ++-- .../src/api-item-transforms/Utilities.ts | 1 + .../api-item-transforms/test/Transformation.test.ts | 3 +++ .../src/documentation-domain/DocumentNode.ts | 11 +++++++++++ .../src/markdown-renderer/test/RenderDocument.test.ts | 1 + 8 files changed, 27 insertions(+), 4 deletions(-) diff --git a/tools/api-markdown-documenter/api-report/api-markdown-documenter.api.md b/tools/api-markdown-documenter/api-report/api-markdown-documenter.api.md index 53e0747474da..b6b5b89cf065 100644 --- a/tools/api-markdown-documenter/api-report/api-markdown-documenter.api.md +++ b/tools/api-markdown-documenter/api-report/api-markdown-documenter.api.md @@ -219,6 +219,7 @@ export type DocumentBoundaries = ApiMemberKind[]; // @public export class DocumentNode implements Parent, DocumentNodeProps { constructor(props: DocumentNodeProps); + readonly apiItemName: string; readonly children: SectionNode[]; readonly filePath: string; readonly frontMatter?: string; @@ -227,6 +228,7 @@ export class DocumentNode implements Parent, DocumentNodeProps { // @public export interface DocumentNodeProps { + readonly apiItemName: string; readonly children: SectionNode[]; readonly filePath: string; readonly frontMatter?: string; diff --git a/tools/api-markdown-documenter/package.json b/tools/api-markdown-documenter/package.json index b73821d8ede0..5e4e4254caf9 100644 --- a/tools/api-markdown-documenter/package.json +++ b/tools/api-markdown-documenter/package.json @@ -1,6 +1,6 @@ { "name": "@fluid-tools/api-markdown-documenter", - "version": "0.7.1", + "version": "0.7.2", "description": "Processes .api.json files generated by API-Extractor and generates Markdown documentation from them.", "homepage": "https://fluidframework.com", "repository": { diff --git a/tools/api-markdown-documenter/src/RenderMarkdown.ts b/tools/api-markdown-documenter/src/RenderMarkdown.ts index 43ac05aff179..ce1ed35930f0 100644 --- a/tools/api-markdown-documenter/src/RenderMarkdown.ts +++ b/tools/api-markdown-documenter/src/RenderMarkdown.ts @@ -65,6 +65,10 @@ export async function renderDocumentsAsMarkdown( config: MarkdownRenderConfiguration, outputDirectoryPath: string, ): Promise { + const { logger } = config; + + logger?.verbose("Rendering documents as Markdown and writing to disk..."); + const completeRenderConfig = getMarkdownRenderConfigurationWithDefaults(config); await FileSystem.ensureEmptyFolderAsync(outputDirectoryPath); @@ -80,5 +84,6 @@ export async function renderDocumentsAsMarkdown( }); }), ); - console.log("Documents written to disk."); + + logger?.success("Markdown documents written to disk."); } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts index 941901f9d447..881164bc784c 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/TransformApiModel.ts @@ -36,7 +36,7 @@ export function transformApiModel( const config = getApiItemTransformationConfigurationWithDefaults(transformConfig); const { apiModel, logger, skipPackage } = config; - logger.info(`Generating Markdown documentation for API Model ${apiModel.displayName}...`); + logger.verbose(`Generating documentation for API Model...`); // If a package has multiple entry-points, it's possible for the same API item to appear under more than one // entry-point (i.e., we are traversing a graph, rather than a tree). @@ -112,7 +112,7 @@ export function transformApiModel( } } - logger.success("Documents generated!"); + logger.success("API Model documents generated!"); return [...documents.values()]; } diff --git a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts index d8ccb5e5b841..c19d3f57e506 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/Utilities.ts @@ -44,6 +44,7 @@ export function createDocument( } return new DocumentNode({ + apiItemName: documentItem.displayName, children: contents, filePath: getFilePathForApiItem(documentItem, config), frontMatter, diff --git a/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts b/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts index 37fe92b71eb7..b756d2a6ec19 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts +++ b/tools/api-markdown-documenter/src/api-item-transforms/test/Transformation.test.ts @@ -364,6 +364,7 @@ describe("ApiItem to Documentation transformation tests", () => { // The model-level doc in this case isn't particularly interesting, so we will skip evaluating it. const expectedPackageDoc = new DocumentNode({ + apiItemName: "test-package", filePath: "test-package.md", children: [ new SectionNode( @@ -401,6 +402,7 @@ describe("ApiItem to Documentation transformation tests", () => { expect(documents[1]).to.deep.equal(expectedPackageDoc); const expectedEntryPointADoc = new DocumentNode({ + apiItemName: "entry-point-a", filePath: "test-package/entry-point-a-entrypoint.md", children: [ new SectionNode( @@ -484,6 +486,7 @@ describe("ApiItem to Documentation transformation tests", () => { expect(documents[2]).to.deep.equal(expectedEntryPointADoc); const expectedEntryPointBDoc = new DocumentNode({ + apiItemName: "entry-point-b", filePath: "test-package/entry-point-b-entrypoint.md", children: [ new SectionNode( diff --git a/tools/api-markdown-documenter/src/documentation-domain/DocumentNode.ts b/tools/api-markdown-documenter/src/documentation-domain/DocumentNode.ts index 547dcdcf8dbb..113ca7950b53 100644 --- a/tools/api-markdown-documenter/src/documentation-domain/DocumentNode.ts +++ b/tools/api-markdown-documenter/src/documentation-domain/DocumentNode.ts @@ -11,6 +11,11 @@ import { SectionNode } from "./SectionNode"; * {@link DocumentNode} construction properties. */ export interface DocumentNodeProps { + /** + * Name of the API item from which this document node was generated. + */ + readonly apiItemName: string; + /** * Child nodes. * @@ -43,6 +48,11 @@ export class DocumentNode implements UnistParent, DocumentNodeProps */ public readonly type = DocumentationNodeType.Document; + /** + * {@inheritDoc DocumentNodeProps.apiItemName} + */ + public readonly apiItemName: string; + /** * {@inheritDoc DocumentNodeProps.children} */ @@ -59,6 +69,7 @@ export class DocumentNode implements UnistParent, DocumentNodeProps public readonly frontMatter?: string; public constructor(props: DocumentNodeProps) { + this.apiItemName = props.apiItemName; this.children = props.children; this.filePath = props.filePath; this.frontMatter = props.frontMatter; diff --git a/tools/api-markdown-documenter/src/markdown-renderer/test/RenderDocument.test.ts b/tools/api-markdown-documenter/src/markdown-renderer/test/RenderDocument.test.ts index 486dda4ef7cd..bf742a81266a 100644 --- a/tools/api-markdown-documenter/src/markdown-renderer/test/RenderDocument.test.ts +++ b/tools/api-markdown-documenter/src/markdown-renderer/test/RenderDocument.test.ts @@ -18,6 +18,7 @@ import { getRenderConfigurationWithDefaults } from "../configuration"; describe("Document rendering tests", () => { it("Renders a simple document", () => { const document = new DocumentNode({ + apiItemName: "Foo", children: [ new SectionNode( [