Skip to content

Commit

Permalink
fix(docs): API docs build (microsoft#17851)
Browse files Browse the repository at this point in the history
Variables `alphaWarningSpan` and `betaWarningSpan` were not defined in
the local module, and so the default layout would fail to render docs
for any item marked as `@alpha` or `@beta` (iff they were preserved in
the API report generated by API-Extractor, which was not previously true
for `@alpha` members, but was for `@beta` ones).

This PR fixes the build by correctly defining those variables.
  • Loading branch information
Josmithr authored Oct 18, 2023
1 parent 52d49a7 commit 639a54b
Showing 1 changed file with 20 additions and 4 deletions.
24 changes: 20 additions & 4 deletions docs/api-markdown-documenter/api-documentation-layout.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ const {
getReleaseTag,
LayoutUtilities,
SectionNode,
SpanNode,
transformTsdocNode,
HeadingNode,
} = require("@fluid-tools/api-markdown-documenter");
Expand All @@ -20,6 +21,13 @@ const { AlertNode } = require("./alert-node");
const customExamplesSectionTitle = "Usage";
const customThrowsSectionTitle = "Error Handling";

const alphaWarning = SpanNode.createFromPlainText(
"WARNING: This API is provided as an alpha preview and may change without notice. Use at your own risk.",
);
const betaWarning = SpanNode.createFromPlainText(
"WARNING: This API is provided as a beta preview and may change without notice. Use at your own risk.",
);

/**
* Default content layout for all API items.
*
Expand Down Expand Up @@ -69,9 +77,9 @@ function layoutContent(apiItem, itemSpecificContent, config) {
// Render alpha/beta notice if applicable
const releaseTag = getReleaseTag(apiItem);
if (releaseTag === ReleaseTag.Alpha) {
sections.push(new SectionNode([alphaWarningSpan]));
sections.push(new SectionNode([alphaWarning]));
} else if (releaseTag === ReleaseTag.Beta) {
sections.push(new SectionNode([betaWarningSpan]));
sections.push(new SectionNode([betaWarning]));
}

// Render signature (if any)
Expand All @@ -87,7 +95,11 @@ function layoutContent(apiItem, itemSpecificContent, config) {
}

// Render examples (if any)
const renderedExamples = LayoutUtilities.createExamplesSection(apiItem, config, customExamplesSectionTitle);
const renderedExamples = LayoutUtilities.createExamplesSection(
apiItem,
config,
customExamplesSectionTitle,
);
if (renderedExamples !== undefined) {
sections.push(renderedExamples);
}
Expand All @@ -99,7 +111,11 @@ function layoutContent(apiItem, itemSpecificContent, config) {
}

// Render @throws content (if any)
const renderedThrows = LayoutUtilities.createThrowsSection(apiItem, config, customThrowsSectionTitle);
const renderedThrows = LayoutUtilities.createThrowsSection(
apiItem,
config,
customThrowsSectionTitle,
);
if (renderedThrows !== undefined) {
sections.push(renderedThrows);
}
Expand Down

0 comments on commit 639a54b

Please sign in to comment.