refactor(api-markdown-documenter): Allow deeper customization of output folder structure #23366
Conversation
github-actions
bot
added
public api change
Josmithr
force-pushed
the
api-markdown-documenter/hierarchy-config
branch
from
a9d189d to
3071431
Compare
tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts
Outdated
Show resolved
Hide resolved
tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts
Outdated
Show resolved
Hide resolved
tools/api-markdown-documenter/src/utilities/ApiItemUtilities.ts
Outdated
Show resolved
Hide resolved
| * Copyright (c) Microsoft Corporation and contributors. All rights reserved. | ||
| * Licensed under the MIT License. | ||
| */ | ||
|
|
There was a problem hiding this comment.
This module is more or less the core of these changes. Control over the output suite hierarchy is unified here (in place of the old documentBoundaries and hierarchyBoundaries properties on DocumentationSuiteConfiguration.
The core goal of these changes is to allow configuring where an API item's document is placed relative to its directory (inside or outside), for items that yield folder hierarchy.
| * @remarks Must be either a folder or document hierarchy configuration. | ||
| * | ||
| * @privateRemarks | ||
| * TODO: Allow all hierarchy configurations for packages. |
| * When a package only has a single entrypoint, this is skipped entirely and entrypoint children are rendered directly to the package document. | ||
| * | ||
| * @privateRemarks | ||
| * TODO: Allow all hierarchy configurations for packages. |
| @@ -0,0 +1,176 @@ | |||
| /*! | |||
There was a problem hiding this comment.
The new type hierarchies make it more difficult to share tests directly. As a result, this module (previously EndtoEndTests.ts has been refactored to share common utilities, and the actual test definitions have been moved into the individual end-to-end test modules.
| /** | ||
| * Test hierarchy configs | ||
| * | ||
| * @privateRemarks TODO: Formalize and export some of these as pre-canned solutions? |
| ]; | ||
| ], | ||
|
|
||
| // TODO: deep config |
There was a problem hiding this comment.
TODO before merging
| ]; | ||
| ], | ||
|
|
||
| // TODO: deep config |
There was a problem hiding this comment.
TODO before merging
| apiModel = await loadModel({ modelDirectoryPath }); | ||
| }); | ||
|
|
||
| describe("Ensure no duplicate document paths", () => { |
There was a problem hiding this comment.
This test case was previously redundantly captured by both the Markdown and HTML end-to-end test suites. Extracted into a separate suite for just the API Model -> Document transformation.
| type RenderDocumentAsHtmlConfiguration, | ||
| renderDocumentAsHtml, | ||
| } from "../renderers/index.js"; | ||
| import { HtmlRenderer, loadModel } from "../index.js"; |
There was a problem hiding this comment.
Both HTML and Markdown end-to-end test suites have been updated to leverage the public API, rather than using internal implementation details.
Josmithr
force-pushed
the
api-markdown-documenter/hierarchy-config
branch
from
dba826a to
ba59e5a
Compare
|
🔗 No broken links found! ✅ Your attention to detail is admirable. linkcheck output |
Primary functional changes:
Required some substantial changes to the API shape.
Note: to keep things relatively simple, system defaults and test configurations have been intentionally made to preserve existing system default behaviors. As a result, you'll notice that none of the end-to-end tests have updated collateral. However, the intention is to update default behaviors, and to add more end-to-end test configurations. For now, I have left a handful of TODOs in configuration defaults and test configurations - I will address those in a follow-up PR.