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.

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<SectionNode>, 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<SectionNode>, DocumentNodeProps {
 
 // @public
 export interface DocumentNodeProps {
+    readonly apiItemName: string;
     readonly children: SectionNode[];
     readonly filePath: string;
     readonly frontMatter?: string;

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": {

tools/api-markdown-documenter/src/RenderMarkdown.ts

@@ -65,6 +65,10 @@ export async function renderDocumentsAsMarkdown(
 	config: MarkdownRenderConfiguration,
 	outputDirectoryPath: string,
 ): Promise<void> {
+	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.");
 }

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()];
 }

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,

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(

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<SectionNode>, 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<SectionNode>, 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;

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(
 					[