feat: Refine api reference docs generation process (#8229)

* fix: Scope amplify-js references build to make room for other packages

* feat: Refactor api generation

* Wrapping up exploration

* feat: Add script to parse adjacent package typedoc references

* chore: Cleanup type references with a fresh JS build

* Comment update

* Remove amplify-data

* Remove the old apiReferences.json file

* Remove test string

* Updates from reviewing PR

* Revert references json to old version

* PR cleanup

* Update gitignore

* PR comment fixes

Author: stocaaro

.github/workflows/update_references.yml

@@ -71,6 +71,7 @@ public/**/**/nextImageExportOptimizer/
 public/next-image-export-optimizer-hashes.json
 src/directory/directory.json
 src/directory/flatDirectory.json
+src/references/raw-references.json
 
 #amplify-do-not-edit-begin
 amplify/\#current-cloud-backend

.gitignore

@@ -119,7 +119,8 @@
     "prepare": "husky install",
     "analyze": "ANALYZE=true yarn next-build",
     "prebuild": "node src/directory/generateDirectory.mjs && node src/directory/generateFlatDirectory.mjs",
-    "lint": "next lint"
+    "lint": "next lint",
+    "clean-references": "node tasks/clean-references.mjs"
   },
   "packageManager": "[email protected]"
 }

package.json

@@ -2,7 +2,7 @@ import { View } from '@aws-amplify/ui-react';
 import { MDXHeading } from '../MDXComponents';
 import { Promise } from './display/Promise';
 import { ApiComment } from './ApiComment';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 import { ParameterType } from './display';
 
 export const FunctionReturn = ({ functionReturn, sigName }) => {

src/components/ApiDocs/FunctionReturn.tsx

@@ -4,7 +4,7 @@ import { ApiComment } from './ApiComment';
 import { Parameters } from './Parameters';
 import { Throws } from './Throws';
 import { FunctionReturn } from './FunctionReturn';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 
 export const FunctionSignature = ({ sig }) => {
   const sigObject = references[sig];

src/components/ApiDocs/FunctionSignature.tsx

@@ -2,7 +2,7 @@ import { View } from '@aws-amplify/ui-react';
 import { MDXHeading, MDXTable } from '../MDXComponents';
 import { ApiComment } from './ApiComment';
 import { ParameterType } from './display';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 
 export const Parameters = ({ parameters, sigName }) => {
   const paramObjects = parameters.map((id) => references[id]);

src/components/ApiDocs/Parameters.tsx

@@ -3,7 +3,7 @@ import { Fragment } from 'react';
 import { FunctionReference } from './FunctionReference';
 import { Divider, View, Flex } from '@aws-amplify/ui-react';
 import { API_CATEGORIES, API_SUB_CATEGORIES } from '@/data/api-categories.mjs';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 import { MDXHeading } from '../MDXComponents';
 
 export const ReferencePage = ({ category }) => {

src/components/ApiDocs/ReferencePage.tsx

@@ -5,7 +5,7 @@ import { IconX } from '../../Icons';
 import { ParameterType } from './ParameterType';
 import { ApiComment } from '../ApiComment';
 import { LinkDataType, TypeLinkInterface } from './TypeLink';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 import { useRef } from 'react';
 
 interface ApiModalInterface {

src/components/ApiDocs/display/ApiModal.tsx

@@ -2,7 +2,7 @@ import { View } from '@aws-amplify/ui-react';
 import { TypeLink } from './TypeLink';
 import { LinkDataType } from './TypeLink';
 import React from 'react';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 
 interface typeDataType {
   typeArguments?: LinkDataType[];

src/components/ApiDocs/display/ParameterType.tsx

@@ -1,7 +1,7 @@
 import { useContext } from 'react';
 import { TypeContext } from '@/components/ApiDocs/ApiModalProvider';
 import { View } from '@aws-amplify/ui-react';
-import references from '@/directory/apiReferences.json';
+import references from '@/directory/apiReferences/amplify-js.json';
 
 export interface LinkDataType {
   name: string;