Feature/api docs (#7990)

* initial template implementation

* additional template functionality

* update modal

* add api references json

* add api categories

* update to template and display

* revert changes to dev script

* pass references to components

* remove build cache

* remove pass through references

* clean references

* add categories into clean references

* update references

* update references with correct categories

* update references

* cleaned references

* update to clean references

* update header and Toc

* update directories

* update generate directory

* add sub categories

* move references and rename to raw-references

* update api docs template

* undo unwanted changes

* remove colons, some type updates, add keys (#7952)

* update TypeLink to output a button (#7953)

* chore(api-docs-template): Update ApiModal styling/markup. Move breadcrumbs to ApiModalBreadcrumbs (#7956)

* update Modal styling/ add Breadcrumbs

* remove commented out code

* update to generateDirectory to add api reference pages (#7950)

Co-authored-by: Jacob Logan <[email protected]>

* add getApiStaticPath util function (#7949)

* add getApiStaticPath util function

* add typing

* update type and comment on paths

---------

Co-authored-by: Jacob Logan <[email protected]>

* parse out markdown links in comments

* update link to display literal type

* Feature/api docs workflow (#7948)

* update api disapatch workflow

* set github commit user in workflow

* update references file name

* rename raw and clean references

* update workflow add comments to clean script

---------

Co-authored-by: Jacob Logan <[email protected]>

* add dark mode to modal description text

* update api function returns to use typeParameters

* remove space in promise display

* close modal when click outside modal (#7969)

Co-authored-by: katiegoines <[email protected]>

* focus modal on open (#7970)

Co-authored-by: katiegoines <[email protected]>

* fix typo;

* fix error in modal close

* format "Returns" as code (#7971)

* .

* format Returns as code

---------

Co-authored-by: katiegoines <[email protected]>

* add api link legend

* update breadcrumbs separator, render nested typeArgs, render nested arraytypes

* add function type display

* add error type

* update api legend and link colors

* update cleaned references location

* update base references files

* update scroll behavior

* reverting uneeded changes to base.scss

* update formatting

* add spacing to breadcrumbs

* remove extra space and add legend header

* add formatting to api comments (#8000)

Co-authored-by: Jacob Logan <[email protected]>

* update list parsing

---------

Co-authored-by: Jacob Logan <[email protected]>
Co-authored-by: Heather Buchel <[email protected]>
Co-authored-by: Katie Goines <[email protected]>
Co-authored-by: katiegoines <[email protected]>

Author: 5 people

.github/workflows/update_references.yml

@@ -0,0 +1,47 @@
+name: Receive repository dispatch event
+
+on:
+  # Listen to a repository dispatch event by the name of `dispatch-event`
+  repository_dispatch:
+    types: [update-references]
+  workflow_dispatch:
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:
+  create-pull-request:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+
+      - name: Setup Node.js 20
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        with:
+          node-version: 20.x
+
+      - name: Set github commit user
+        env:
+          GITHUB_EMAIL: ${{ vars.GH_EMAIL }}
+          GITHUB_USER: ${{ vars.GH_USER }}
+        run: |
+          git config --global user.email $GITHUB_EMAIL
+          git config --global user.name $GITHUB_USER
+
+        # Set branch name to be used as environment variable
+      - name: Set Branch Name
+        run: echo "BRANCH_NAME=$(echo update-ref-$(date +%s))" >> $GITHUB_ENV
+
+        # Create new branch, download, and commit changes to the new branch
+      - name: Create new branch
+        run: |
+          git checkout -b ${{ env.BRANCH_NAME }}
+          curl -L -o ${{ vars.REF_LOC }} ${{ vars.REMOTE_REF }}
+          node tasks/clean-references.mjs
+          git add ${{ vars.REF_LOC }} ${{ vars.CLEAN_LOC }}
+          git commit -m "updating references"
+          git push -u origin ${{ env.BRANCH_NAME }}
+
+        # Open pull request
+      - name: Create Pull Request
+        run: gh pr create -B main -H ${{ env.BRANCH_NAME }} --title 'Merge ${{ env.BRANCH_NAME }} into main' --body 'Created by Github action'

mdx-components.tsx

@@ -22,6 +22,7 @@ import { InternalLinkButton } from './src/components/InternalLinkButton';
 import { Grid, View } from '@aws-amplify/ui-react';
 import { Columns } from './src/components/Columns';
 import { Video } from './src/components/Video';
+import { ReferencePage } from './src/components/ApiDocs';
 
 const ResponsiveImage = (props) => (
   <ExportedImage style={{ height: 'auto' }} {...props} />
@@ -71,6 +72,7 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
     Columns,
     Video,
     View,
+    ReferencePage,
     ...components
   };
 }

src/components/ApiDocs/ApiComment.tsx

@@ -0,0 +1,38 @@
+import { Fragment } from 'react';
+import { View } from '@aws-amplify/ui-react';
+import { parseMarkdownLinks, parseMarkdown } from '@/utils/parseMdxLinks';
+
+interface ApiCommentProps {
+  apiComment?: any[];
+  codeBlock?: boolean | undefined;
+}
+
+export const ApiComment = ({ apiComment, codeBlock }: ApiCommentProps) => {
+  if (!apiComment) return null;
+  const firstItem = apiComment[0];
+  if (!firstItem?.text?.replaceAll('-', '')?.trim()) {
+    apiComment.shift();
+  }
+  const commentList = apiComment.map((snippet, idx) => {
+    if (snippet.kind === 'code') {
+      return <code key={idx}>{snippet.text.replaceAll('`', '')}</code>;
+    } else {
+      const text = snippet.text;
+      if (idx === 0 && codeBlock) {
+        const words = text.split(' ');
+        return (
+          <Fragment key={`snippet-${idx}`}>
+            <code>{words[0]}</code>
+            {words.slice(1).join(' ')}
+          </Fragment>
+        );
+      } else {
+        return parseMarkdownLinks(text);
+      }
+    }
+  });
+
+  const parsedComments = parseMarkdown(commentList as (string | JSX.Element)[]);
+
+  return <View>{parsedComments}</View>;
+};

src/components/ApiDocs/ApiModalProvider.tsx

@@ -0,0 +1,56 @@
+import { useState, createContext } from 'react';
+import { LinkDataType } from './display/TypeLink';
+import { ApiModal } from './display/ApiModal';
+
+export const TypeContext = createContext({
+  setModalData: (data) => data,
+  modalOpen: () => {},
+  addBreadCrumb: (data) => data,
+  setBC: (data) => data
+});
+
+export const ApiModalProvider = ({ children }) => {
+  const [modalData, setModalData] = useState({});
+  const [showModal, setShowModal] = useState(false);
+  const [breadCrumbs, setBreadCrumbs] = useState<LinkDataType[]>([]);
+
+  const modalOpen = () => {
+    setShowModal(true);
+  };
+  const closeModal = () => {
+    setShowModal(false);
+  };
+
+  const addBreadCrumb = (bc) => {
+    breadCrumbs.push(bc);
+    setBreadCrumbs(breadCrumbs);
+  };
+
+  const setBC = (bc) => {
+    setBreadCrumbs(bc);
+  };
+
+  const clearBC = () => {
+    setBreadCrumbs([]);
+  };
+
+  const value = {
+    setModalData,
+    modalOpen,
+    addBreadCrumb,
+    setBC
+  };
+
+  return (
+    <TypeContext.Provider value={value}>
+      <ApiModal
+        data={modalData}
+        showModal={showModal}
+        close={closeModal}
+        breadCrumbs={breadCrumbs}
+        clearBC={clearBC}
+      />
+      {children}
+    </TypeContext.Provider>
+  );
+};

src/components/ApiDocs/FunctionReference.tsx

@@ -0,0 +1,12 @@
+import { View } from '@aws-amplify/ui-react';
+import { FunctionSignature } from './FunctionSignature';
+
+export const FunctionReference = ({ func }) => {
+  return (
+    <View>
+      {func.signatures.map((sig, index) => (
+        <FunctionSignature sig={sig} key={`signature-${index}`} />
+      ))}
+    </View>
+  );
+};

src/components/ApiDocs/FunctionReturn.tsx

@@ -0,0 +1,35 @@
+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 { ParameterType } from './display';
+
+export const FunctionReturn = ({ functionReturn, sigName }) => {
+  const name = functionReturn.name;
+  let display, description;
+  if (name === 'Promise') {
+    const returnType = references[functionReturn.typeArguments[0].target];
+    display = <Promise typeObject={functionReturn} />;
+    if (returnType?.comment?.summary) {
+      description = <ApiComment apiComment={returnType.comment.summary} />;
+    }
+  } else {
+    const returnType = references[functionReturn.target];
+    display = <ParameterType typeData={functionReturn} />;
+    if (returnType?.comment?.summary) {
+      description = <ApiComment apiComment={returnType.comment.summary} />;
+    }
+  }
+  return (
+    <View>
+      <MDXHeading level={3} id={`${sigName}-Returns`}>
+        Returns
+      </MDXHeading>
+
+      <code>{display}</code>
+
+      {description}
+    </View>
+  );
+};

src/components/ApiDocs/FunctionSignature.tsx

@@ -0,0 +1,44 @@
+import { View } from '@aws-amplify/ui-react';
+import { MDXHeading } from '../MDXComponents';
+import { ApiComment } from './ApiComment';
+import { Parameters } from './Parameters';
+import { Throws } from './Throws';
+import { FunctionReturn } from './FunctionReturn';
+import references from '@/directory/apiReferences.json';
+
+export const FunctionSignature = ({ sig }) => {
+  const sigObject = references[sig];
+  const description = sigObject?.comment?.summary;
+  const parameters = sigObject?.parameters;
+  const throws = sigObject?.comment?.blockTags?.filter(
+    (tagObject) => tagObject['tag'] === '@throws'
+  );
+  const returns = sigObject?.type;
+  return (
+    <View>
+      <MDXHeading level={2} id={`${sigObject.name}-${sigObject.id}`}>
+        {sigObject.name}
+      </MDXHeading>
+
+      {description && <ApiComment apiComment={description} />}
+
+      {parameters && (
+        <Parameters
+          parameters={parameters}
+          sigName={`${sigObject.name}-${sigObject.id}`}
+        />
+      )}
+
+      {throws && throws.length > 0 && (
+        <Throws throws={throws} sigName={`${sigObject.name}-${sigObject.id}`} />
+      )}
+
+      {returns && (
+        <FunctionReturn
+          functionReturn={returns}
+          sigName={`${sigObject.name}-${sigObject.id}`}
+        />
+      )}
+    </View>
+  );
+};

src/components/ApiDocs/Parameters.tsx

@@ -0,0 +1,46 @@
+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';
+
+export const Parameters = ({ parameters, sigName }) => {
+  const paramObjects = parameters.map((id) => references[id]);
+  return (
+    <View>
+      <MDXHeading level={3} id={`${sigName}-Parameters`}>
+        Parameters
+      </MDXHeading>
+      <MDXTable>
+        <thead>
+          <tr>
+            <th>Option</th>
+            <th>Required</th>
+            <th>Type</th>
+            <th>Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {paramObjects.map((option) => {
+            return (
+              <tr key={option.id}>
+                <td>
+                  <code>{option.name}</code>
+                </td>
+                <td>{option?.flags?.isOptional ? 'false' : 'true'}</td>
+                <td>
+                  <ParameterType typeData={option.type} />
+                </td>
+                <td>
+                  {option?.comment?.summary && (
+                    <ApiComment apiComment={option.comment.summary} />
+                  )}
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </MDXTable>
+    </View>
+  );
+};

src/components/ApiDocs/ReferencePage.tsx

@@ -0,0 +1,40 @@
+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 { MDXHeading } from '../MDXComponents';
+
+export const ReferencePage = ({ category }) => {
+  category = API_CATEGORIES[category] || API_SUB_CATEGORIES[category];
+  const cat = references['categories'].find(
+    (catObject) => catObject.name === category
+  );
+  return (
+    <View className={'reference-page'}>
+      {cat?.children?.map((child, idx) => (
+        <Fragment key={`reference-${idx}`}>
+          {idx !== 0 && <Divider marginTop={'medium'} />}
+          <FunctionReference func={child} />
+        </Fragment>
+      ))}
+      <Divider marginTop={'large'} marginBottom={'large'} />
+      <MDXHeading level={4}>Link Color Legend</MDXHeading>
+      <Flex className="api-legend-container">
+        <Flex>
+          <View as="span" className="api-legend interface" />
+          Interface
+        </Flex>
+        <Flex>
+          <View as="span" className="api-legend reference" />
+          Reference
+        </Flex>
+        <Flex>
+          <View as="span" className="api-legend union" />
+          Other
+        </Flex>
+      </Flex>
+    </View>
+  );
+};

src/components/ApiDocs/Throws.tsx

@@ -0,0 +1,21 @@
+import { View } from '@aws-amplify/ui-react';
+import { MDXHeading } from '../MDXComponents';
+import { ApiComment } from './ApiComment';
+
+export const Throws = ({ throws, sigName }) => {
+  return (
+    <View>
+      <MDXHeading level={3} id={`${sigName}-Throws`}>
+        Throws
+      </MDXHeading>
+
+      <ul>
+        {throws.map((error, i) => (
+          <li key={i}>
+            <ApiComment apiComment={error.content} codeBlock={true} />{' '}
+          </li>
+        ))}
+      </ul>
+    </View>
+  );
+};