[dev-tool] use package scope when generating sample apiref link (#32465)

Currently the apiref link template has a hardcoded `@azure` scope so it doesn't work for packages with `@azure-rest` scope. Those packages rely on the customized `apiRefLink` fields in the sample's configuration section of package.json. This PR adds package scope variable to the apiref link template as well so the link generation works for both `@azure` and `@azure-rest` scopes. These two scopes are the only ones that have SDK API reference pages currently. With this change, customized `apiRefLink` for -rest packages are also removed.
Azure · Jan 10, 2025 · e8acf69 · e8acf69
1 parent 57056dc
commit e8acf69
Show file tree

Hide file tree

Showing 10 changed files with 51 additions and 19 deletions.
diff --git a/common/tools/dev-tool/src/templates/sampleReadme.md.ts b/common/tools/dev-tool/src/templates/sampleReadme.md.ts
@@ -5,6 +5,9 @@ import path from "node:path";
 import YAML from "yaml";
 import { SampleReadmeConfiguration } from "../util/samples/info";
 import { format } from "../util/prettier";
+import { createPrinter } from "../util/printer";
+
+const log = createPrinter("readme-template");
 
 /**
  * Renders the frontmatter of the sample README.
@@ -143,7 +146,7 @@ function exampleNodeInvocation(info: SampleReadmeConfiguration) {
 }
 
 /**
- * Create a link to the package.
+ * Creates a link to the package.
  * @param info - the README configuration
  * @returns a link to the project
  */
@@ -154,16 +157,48 @@ function createReadmeLink(info: SampleReadmeConfiguration) {
   return `https://github.com/Azure/azure-sdk-for-js/tree/main/${fragment}/README.md`;
 }
 
+/**
+ * Checks whether a url exists
+ * @param url -
+ * @returns true if the url is accessible; false otherwise
+ */
+async function urlExists(url: string): Promise<boolean> {
+  const res = await fetch(url);
+  await res.text();
+  return res.ok;
+}
+
+/**
+ * Creates link to the SDK package's Api reference page on learn.microsoft.com.
+ * @param info - the README configuration
+ * @returns a link to the api reference page.
+            This methods validates the generated api link first and will return an empty
+            string if the generated link is not valid.
+            No validation is done for customized api ref link that is passed in.
+ */
+async function createApiRef(info: SampleReadmeConfiguration): Promise<string> {
+  if (info.apiRefLink) {
+    return `[apiref]: ${info.apiRefLink}`;
+  } else if (info.scope.startsWith("@azure")) {
+    const link = `https://learn.microsoft.com/javascript/api/${info.scope}/${info.baseName}${info.isBeta ? "?view=azure-node-preview" : ""}`;
+    if (await urlExists(link)) {
+      return `[apiref]: ${link}`;
+    }
+    log.warn(`failed to reach api reference ${link} so not adding it.`);
+  }
+  return "";
+}
+
 /**
  * Creates a README for a sample package from a SampleReadmeConfiguration.
  */
-export default (info: SampleReadmeConfiguration): Promise<string> => {
+export default async (info: SampleReadmeConfiguration): Promise<string> => {
   let stepCount = 1;
   const step = (content: string) => `${stepCount++}. ${content}`;
 
   const language = info.useTypeScript ? "TypeScript" : "JavaScript";
 
-  return format(
+  return await format(
     `${formatFrontmatter(info.frontmatter)}\
 # ${info.productName} client library samples for ${language}${info.isBeta ? " (Beta)" : ""}
 
@@ -241,7 +276,7 @@ Take a look at our [API Documentation][apiref] for more information about the AP
 ${info.customSnippets?.footer ?? ""}
 
 ${fileLinks(info)}
-[apiref]: ${info.apiRefLink ?? `https://learn.microsoft.com/javascript/api/@azure/${info.baseName}`}
+${await createApiRef(info)}
 [freesub]: https://azure.microsoft.com/free/
 ${resourceLinks(info)}
 [package]: ${createReadmeLink(info)}

diff --git a/common/tools/dev-tool/src/util/samples/generation.ts b/common/tools/dev-tool/src/util/samples/generation.ts
@@ -97,8 +97,7 @@ export async function makeSampleGenerationInfo(
 
   const sampleConfiguration = getSampleConfiguration(projectInfo.packageJson);
 
-  const baseName = projectInfo.name.split("/").slice(-1)[0];
-
+  const [scope, baseName] = projectInfo.name.split("/");
   log.debug("Determined project baseName:", baseName);
 
   // A helper to handle configuration errors.
@@ -139,6 +138,7 @@ export async function makeSampleGenerationInfo(
 
   return {
     ...sampleConfiguration,
+    scope,
     baseName,
     packageKeywords:
       projectInfo.packageJson.keywords ??

diff --git a/common/tools/dev-tool/src/util/samples/info.ts b/common/tools/dev-tool/src/util/samples/info.ts
@@ -51,6 +51,10 @@ export const enum OutputKind {
  * Information required for generating sample projects.
  */
 export interface SampleGenerationInfo extends SampleConfiguration {
+  /**
+   * The scope part of the package name. For example, the base part of "@azure/template" is "@azure".
+   */
+  scope: string;
   /**
    * The base part of the package name. For example, the base part of "@azure/template" is "template".
    */

diff --git a/sdk/anomalydetector/ai-anomaly-detector-rest/package.json b/sdk/anomalydetector/ai-anomaly-detector-rest/package.json
@@ -96,8 +96,7 @@
     "productSlugs": [
       "azure"
     ],
-    "disableDocsMs": true,
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/ai-anomaly-detector?view=azure-node-preview"
+    "disableDocsMs": true
   },
   "type": "module",
   "tshy": {

diff --git a/sdk/contentsafety/ai-content-safety-rest/package.json b/sdk/contentsafety/ai-content-safety-rest/package.json
@@ -105,8 +105,7 @@
         "typescript/src/example-data"
       ]
     },
-    "disableDocsMs": true,
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/ai-content-safety?view=azure-node-preview"
+    "disableDocsMs": true
   },
   "type": "module",
   "tshy": {

diff --git a/sdk/maps/maps-route-rest/package.json b/sdk/maps/maps-route-rest/package.json
@@ -37,7 +37,6 @@
     "requiredResources": {
       "Azure Maps Resource": "https://learn.microsoft.com/azure/azure-maps/how-to-create-template"
     },
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/maps-route",
     "disableDocsMs": true
   },
   "//metadata": {

diff --git a/sdk/network/arm-network-rest/package.json b/sdk/network/arm-network-rest/package.json
@@ -100,8 +100,7 @@
     "productSlugs": [
       "azure"
     ],
-    "disableDocsMs": true,
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/arm-network?view=azure-node-preview"
+    "disableDocsMs": true
   },
   "type": "module",
   "tshy": {

diff --git a/sdk/purview/purview-sharing-rest/package.json b/sdk/purview/purview-sharing-rest/package.json
@@ -102,8 +102,7 @@
     "productSlugs": [
       "azure"
     ],
-    "disableDocsMs": true,
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/purview-sharing?view=azure-node-preview"
+    "disableDocsMs": true
   },
   "type": "module",
   "tshy": {

diff --git a/sdk/purview/purview-workflow-rest/package.json b/sdk/purview/purview-workflow-rest/package.json
@@ -100,8 +100,7 @@
     "productSlugs": [
       "azure"
     ],
-    "disableDocsMs": true,
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/purview-workflow?view=azure-node-preview"
+    "disableDocsMs": true
   },
   "type": "module",
   "tshy": {

diff --git a/sdk/servicefabric/arm-servicefabric-rest/package.json b/sdk/servicefabric/arm-servicefabric-rest/package.json
@@ -99,8 +99,7 @@
     "productSlugs": [
       "azure"
     ],
-    "disableDocsMs": true,
-    "apiRefLink": "https://learn.microsoft.com/javascript/api/@azure-rest/arm-servicefabric?view=azure-node-preview"
+    "disableDocsMs": true
   },
   "type": "module",
   "tshy": {