improvement(api-markdown-documenter): Make uriRoot parameter optional (#23634)

The `uriRoot` parameter is an option for changing the root path for all
generated links. A sensible default for this parameter is nothing (i.e.
`""`). This PR makes the parameter optional, and simplifies a couple of
test cases by omitting that value.

Author: Josmithr

tools/api-markdown-documenter/CHANGELOG.md

@@ -5,6 +5,8 @@
 -   The default suite structure has been updated as follows:
     -   `Package` and `Namespace` items now generate documents _inside_ of their own folder hierarchy, yielding documents named "index".
     -   `Enum` and `TypeAlias` items now generate their own documents (rather than being rendered as sections under their parent document).
+-   `uriRoot` parameter is now optional.
+    The default value is "".
 
 ### ⚠ BREAKING CHANGES
 
@@ -32,7 +34,7 @@ const apiModel = await loadModel({
 
 const transformConfig = {
 	apiModel,
-	uriRoot: ".",
+	uriRoot: "",
 };
 
 await MarkdownRenderer.renderApiModel(transformConfig, {}, { outputDirectoryPath });
@@ -53,7 +55,7 @@ const apiModel = await loadModel({
 
 await MarkdownRenderer.renderApiModel({
 	apiModel,
-	uriRoot: ".",
+	uriRoot: "", // Note: this parameter is also now optional. Default: "".
 	outputDirectoryPath,
 });
 ```

tools/api-markdown-documenter/README.md

@@ -86,7 +86,6 @@ const apiModel = await loadModel({
 
 await MarkdownRenderer.renderApiModel({
 	apiModel,
-	uriRoot: ".",
 	outputDirectoryPath,
 });
 ```

tools/api-markdown-documenter/api-report/api-markdown-documenter.alpha.api.md

@@ -52,18 +52,19 @@ export { ApiItemKind }
 export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, DocumentationSuiteConfiguration, Required<LoggingConfiguration> {
     readonly defaultSectionLayout: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
     readonly transformations: ApiItemTransformations;
+    readonly uriRoot: string;
 }
 
 // @public @sealed
 export interface ApiItemTransformationConfigurationBase {
     readonly apiModel: ApiModel;
-    readonly uriRoot: string;
 }
 
 // @public
 export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, DocumentationSuiteOptions, LoggingConfiguration {
     readonly defaultSectionLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
     readonly transformations?: Partial<ApiItemTransformations>;
+    readonly uriRoot?: string | undefined;
 }
 
 // @public

tools/api-markdown-documenter/api-report/api-markdown-documenter.beta.api.md

@@ -52,18 +52,19 @@ export { ApiItemKind }
 export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, DocumentationSuiteConfiguration, Required<LoggingConfiguration> {
     readonly defaultSectionLayout: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
     readonly transformations: ApiItemTransformations;
+    readonly uriRoot: string;
 }
 
 // @public @sealed
 export interface ApiItemTransformationConfigurationBase {
     readonly apiModel: ApiModel;
-    readonly uriRoot: string;
 }
 
 // @public
 export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, DocumentationSuiteOptions, LoggingConfiguration {
     readonly defaultSectionLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
     readonly transformations?: Partial<ApiItemTransformations>;
+    readonly uriRoot?: string | undefined;
 }
 
 // @public

tools/api-markdown-documenter/api-report/api-markdown-documenter.public.api.md

@@ -52,18 +52,19 @@ export { ApiItemKind }
 export interface ApiItemTransformationConfiguration extends ApiItemTransformationConfigurationBase, DocumentationSuiteConfiguration, Required<LoggingConfiguration> {
     readonly defaultSectionLayout: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
     readonly transformations: ApiItemTransformations;
+    readonly uriRoot: string;
 }
 
 // @public @sealed
 export interface ApiItemTransformationConfigurationBase {
     readonly apiModel: ApiModel;
-    readonly uriRoot: string;
 }
 
 // @public
 export interface ApiItemTransformationOptions extends ApiItemTransformationConfigurationBase, DocumentationSuiteOptions, LoggingConfiguration {
     readonly defaultSectionLayout?: (apiItem: ApiItem, childSections: SectionNode[] | undefined, config: ApiItemTransformationConfiguration) => SectionNode[];
     readonly transformations?: Partial<ApiItemTransformations>;
+    readonly uriRoot?: string | undefined;
 }
 
 // @public

tools/api-markdown-documenter/examples/RenderHtml.ts

@@ -15,6 +15,5 @@ const apiModel = await loadModel({
 
 await HtmlRenderer.renderApiModel({
 	apiModel,
-	uriRoot: ".",
 	outputDirectoryPath,
 });

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

@@ -15,6 +15,5 @@ const apiModel = await loadModel({
 
 await MarkdownRenderer.renderApiModel({
 	apiModel,
-	uriRoot: ".",
 	outputDirectoryPath,
 });

tools/api-markdown-documenter/src/api-item-transforms/configuration/Configuration.ts

@@ -40,11 +40,6 @@ export interface ApiItemTransformationConfigurationBase {
 	 * If you need to generate a model from API reports on disk, see {@link loadModel}.
 	 */
 	readonly apiModel: ApiModel;
-
-	/**
-	 * Default root URI used when generating content links.
-	 */
-	readonly uriRoot: string;
 }
 
 /**
@@ -60,6 +55,14 @@ export interface ApiItemTransformationConfiguration
 	extends ApiItemTransformationConfigurationBase,
 		DocumentationSuiteConfiguration,
 		Required<LoggingConfiguration> {
+	/**
+	 * Default root URI used when generating content links.
+	 *
+	 * @example
+	 * For a generated document `foo/bar` and a `uriRoot` of `docs`, any generated links to that document would be `docs/foo/bar`.
+	 */
+	readonly uriRoot: string;
+
 	/**
 	 * {@inheritDoc ApiItemTransformations}
 	 */
@@ -92,6 +95,13 @@ export interface ApiItemTransformationOptions
 	extends ApiItemTransformationConfigurationBase,
 		DocumentationSuiteOptions,
 		LoggingConfiguration {
+	/**
+	 * {@inheritDoc ApiItemTransformationConfiguration.uriRoot}
+	 *
+	 * @defaultValue ""
+	 */
+	readonly uriRoot?: string | undefined;
+
 	/**
 	 * Optional overrides for the default transformations.
 	 */
@@ -124,7 +134,7 @@ export function getApiItemTransformationConfigurationWithDefaults(
 		...documentationSuiteOptions,
 		transformations,
 		apiModel: options.apiModel,
-		uriRoot: options.uriRoot,
+		uriRoot: options.uriRoot ?? "",
 		logger,
 		defaultSectionLayout,
 	};

tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts

@@ -73,7 +73,6 @@ const testConfigs = new Map<
 	[
 		"deep-config",
 		{
-			uriRoot: "",
 			hierarchy: HierarchyConfigurations.deep,
 		},
 	],

tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts

@@ -73,7 +73,6 @@ const testConfigs = new Map<
 	[
 		"deep-config",
 		{
-			uriRoot: "",
 			hierarchy: HierarchyConfigurations.deep,
 		},
 	],