build: generate AI docs from latest version

INSTUI-5092

Author: ToMESSKa

docs/guides/component-versioning.md

@@ -2,6 +2,7 @@
 title: Component versioning
 category: Guides
 order: 2
+relevantForAI: true
 ---
 
 ## Why components are versioned

packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-llms-file.mts

@@ -72,6 +72,7 @@ function generateAIAccessibleLlmsFile(
 
   let LlmsMarkdownContent = `# Instructure UI (InstUI) - React Component Library\n\n- version ${version} \n\n`
   LlmsMarkdownContent += `- Instructure UI (InstUI) is a comprehensive React component library.\n\n`
+  LlmsMarkdownContent += `- All component documentation below always reflects the latest InstUI version noted above (${version}). Props, types, and examples describe this version.\n\n`
 
   // Add main Documentation section
   LlmsMarkdownContent += `## Documentation\n\n`

packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-markdowns.mts

@@ -173,36 +173,62 @@ function generatePropsTable(
   return propsContent
 }
 
-function generateComponentUsage(doc: DocumentationData): string {
+
+interface VersionImportInfo {
+  version: string
+  versionedPackages: Set<string>
+}
+
+// Versioned packages import from the pinned version path (e.g.
+// `@instructure/ui-badge/v11_7`); non-versioned ones import from the plain
+// package name.
+function buildImportPath(
+  packageName: string,
+  versionImport?: VersionImportInfo
+): string {
+  if (!versionImport) return packageName
+  const shortName = packageName.replace(/^@instructure\//, '')
+  return versionImport.versionedPackages.has(shortName)
+    ? `${packageName}/${versionImport.version}`
+    : packageName
+}
+
+function generateComponentUsage(
+  doc: DocumentationData,
+  versionImport?: VersionImportInfo
+): string {
   if (!isComponent(doc)) return ''
 
   const { id, displayName, packageName } = doc
   const importName = displayName || id
 
   if (!packageName) return ''
 
+  const importPath = buildImportPath(packageName, versionImport)
+
   let usageContent = `### Usage\n\n`
 
   usageContent += `Install the package:\n\n\`\`\`shell\nnpm install ${packageName}\n\`\`\`\n\n`
 
   usageContent += `Import the component:\n\n\`\`\`javascript
 /*** ES Modules (with tree shaking) ***/
-import { ${importName} } from '${packageName}'
+import { ${importName} } from '${importPath}'
 \`\`\`\n\n`
 
   return usageContent
 }
 
 function generateComponentMarkdown(
   jsonData: ComponentData,
-  childComponents: ComponentData[] = []
+  childComponents: ComponentData[] = [],
+  versionImport?: VersionImportInfo
 ): string {
   const { displayName, description } = jsonData
 
   let markdownContent = `# ${displayName}\n\n`
   markdownContent += `${description}\n\n`
   markdownContent += generatePropsTable(jsonData, childComponents)
-  markdownContent += generateComponentUsage(jsonData)
+  markdownContent += generateComponentUsage(jsonData, versionImport)
 
   return markdownContent
 }
@@ -217,7 +243,9 @@ function generateGuideMarkdown(jsonData: GuideData): string {
 
 async function generateAIAccessibleMarkdowns(
   docsFolder: string,
-  outputDir: string
+  outputDir: string,
+  sourcesDataFilePath = './__build__/markdown-and-sources-data.json',
+  versionImport?: VersionImportInfo
 ): Promise<void> {
   if (!existsSync(outputDir)) {
     mkdirSync(outputDir, { recursive: true })
@@ -262,7 +290,8 @@ async function generateAIAccessibleMarkdowns(
     if (!component.parent) {
       const markdownContent = generateComponentMarkdown(
         component,
-        childComponents
+        childComponents,
+        versionImport
       )
       const fileName = `${
         component.id ||
@@ -273,9 +302,9 @@ async function generateAIAccessibleMarkdowns(
     }
   }
 
-  const buildDir = './__build__/'
-  // create an llms-like index file for docs in the zip
-  generateAIAccessibleLlmsFile(buildDir + 'markdown-and-sources-data.json', {
+  // create an llms-like index file for docs in the zip, from the same
+  // (latest) version's sources data used to generate the markdown files
+  generateAIAccessibleLlmsFile(sourcesDataFilePath, {
     outputFilePath: path.join(outputDir, 'index.md'),
     baseUrl: './',
     summariesFilePath:
@@ -292,3 +321,4 @@ async function generateAIAccessibleMarkdowns(
 }
 
 export { generateAIAccessibleMarkdowns }
+export type { VersionImportInfo }

packages/__docs__/buildScripts/build-docs.mts

@@ -226,22 +226,39 @@ async function buildDocs() {
       JSON.stringify(docsVersionsManifest)
     )
 
-    // Generate AI accessible documentation from default version
-    const defaultVersionDocsDir = buildDir + 'docs/' + defaultVersion + '/'
-    generateAIAccessibleMarkdowns(defaultVersionDocsDir, buildDir + 'markdowns/')
+    // Generate AI accessible documentation from the latest library version.
+    const latestVersion =
+      versionMap.libraryVersions[versionMap.libraryVersions.length - 1] ||
+      defaultVersion
+    const latestVersionDocsDir = buildDir + 'docs/' + latestVersion + '/'
+    const latestVersionSourcesData =
+      latestVersionDocsDir + 'markdown-and-sources-data.json'
+
+    // The latest version plus its versioned packages (the version map's
+    // mapping keys), used to emit versioned import examples in the markdown.
+    const versionImport = {
+      version: latestVersion,
+      versionedPackages: new Set(
+        Object.keys(versionMap.mapping[latestVersion] || {})
+      )
+    }
 
-    generateAIAccessibleLlmsFile(
-      buildDir + 'markdown-and-sources-data.json',
-      {
-        outputFilePath: path.join(buildDir, 'llms.txt'),
-        baseUrl: 'https://instructure.design/markdowns/',
-        summariesFilePath: path.join(
-          __dirname,
-          '../buildScripts/ai-accessible-documentation/summaries-for-llms-file.json'
-        )
-      }
+    await generateAIAccessibleMarkdowns(
+      latestVersionDocsDir,
+      buildDir + 'markdowns/',
+      latestVersionSourcesData,
+      versionImport
     )
 
+    generateAIAccessibleLlmsFile(latestVersionSourcesData, {
+      outputFilePath: path.join(buildDir, 'llms.txt'),
+      baseUrl: 'https://instructure.design/markdowns/',
+      summariesFilePath: path.join(
+        __dirname,
+        '../buildScripts/ai-accessible-documentation/summaries-for-llms-file.json'
+      )
+    })
+
     fs.copyFileSync(
       projectRoot + '/packages/ui-icons/src/generated/legacy/legacy-icons-data.json',
       buildDir + 'legacy-icons-data.json'