Merge pull request #99 from newrelic/jerel/all-api-docs

Add all API docs

src/components/FunctionDefinition.js

@@ -21,7 +21,9 @@ const FunctionDefinition = ({ params, returnValue }) => {
       </span>
       {params.map((param, i) => (
         <div key={i} className={styles.param}>
-          <span className={styles.paramName}>{param.name}: </span>
+          <span className={styles.paramName}>
+            {param.type.startsWith('...') ? `...${param.name}` : param.name}:{' '}
+          </span>
           <span className={styles.type}>{param.type} </span>
           <Markdown
             source={param.description}

src/components/MethodReference.js

@@ -0,0 +1,33 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import ReferenceExample from './ReferenceExample';
+import FunctionDefinition from './FunctionDefinition';
+import Markdown from 'react-markdown';
+import styles from './MethodReference.module.scss';
+
+const MethodReference = ({ className, method }) => (
+  <div className={className}>
+    <h3 className={styles.name}>{method.name}</h3>
+    <Markdown className={styles.description} source={method.description} />
+    <FunctionDefinition
+      params={method.params}
+      returnValue={method.returnValue}
+    />
+    {method.examples.map((example, i) => (
+      <ReferenceExample key={i} className={styles.example} example={example} />
+    ))}
+  </div>
+);
+
+MethodReference.propTypes = {
+  className: PropTypes.string,
+  method: PropTypes.shape({
+    name: PropTypes.string.isRequired,
+    description: PropTypes.string,
+    params: FunctionDefinition.propTypes.params,
+    returnValue: FunctionDefinition.propTypes.returnValue,
+    examples: PropTypes.arrayOf(ReferenceExample.propTypes.example),
+  }),
+};
+
+export default MethodReference;

src/components/MethodReference.module.scss

@@ -0,0 +1,15 @@
+.name {
+  padding: 0.125rem 0.25rem;
+  display: inline;
+  color: var(--color-teal-500);
+  background: var(--color-teal-050);
+}
+
+.description {
+  margin-top: 1rem;
+  margin-bottom: 1rem;
+}
+
+.example:not(:last-child) {
+  margin-bottom: 2rem;
+}

src/components/ComponentExample.js → src/components/ReferenceExample.js

@@ -3,8 +3,8 @@ import PropTypes from 'prop-types';
 import formatCode from '../utils/formatCode';
 import github from 'prism-react-renderer/themes/github';
 import { LiveEditor, LiveError, LiveProvider } from 'react-live';
-import styles from './ComponentExample.module.scss';
-import ComponentPreview from './ComponentPreview';
+import styles from './ReferenceExample.module.scss';
+import ReferencePreview from './ReferencePreview';
 
 const platformStateContextMock = {
   timeRange: {
@@ -20,7 +20,7 @@ const nerdletStateContextMock = {
 
 const TRAILING_SEMI = /;\s*$/;
 
-const ComponentExample = ({
+const ReferenceExample = ({
   className,
   example,
   useToastManager,
@@ -57,7 +57,7 @@ const ComponentExample = ({
             disabled={!live}
           >
             {live && (
-              <ComponentPreview
+              <ReferencePreview
                 className={styles.preview}
                 style={previewStyle}
                 useToastManager={useToastManager}
@@ -72,7 +72,7 @@ const ComponentExample = ({
   );
 };
 
-ComponentExample.propTypes = {
+ReferenceExample.propTypes = {
   className: PropTypes.string,
   example: PropTypes.shape({
     label: PropTypes.string.isRequired,
@@ -83,4 +83,4 @@ ComponentExample.propTypes = {
   previewStyle: PropTypes.object,
 };
 
-export default ComponentExample;
+export default ReferenceExample;

src/components/ComponentPreview.js → src/components/ReferencePreview.js

@@ -5,7 +5,7 @@ import { LivePreview } from 'react-live';
 import { CSS_BUNDLE } from '../utils/sdk';
 
 const EXAMPLE_CSS = `
-.nr1-ComponentExample {
+.nr1-ReferenceExample {
   line-height: 1.36;
   font-weight: 400;
   background-color: #fff;
@@ -14,7 +14,7 @@ const EXAMPLE_CSS = `
   font-family: Open Sans,Segoe UI,Tahoma,sans-serif;
 }
 
-.nr1-ComponentExample-ToastManager > div {
+.nr1-ReferenceExample-ToastManager > div {
   position: fixed;
   top: 0;
   right: 0;
@@ -86,7 +86,7 @@ const EXAMPLE_CSS = `
 }
 `;
 
-const ComponentPreview = ({ className, style, useToastManager }) => {
+const ReferencePreview = ({ className, style, useToastManager }) => {
   const [stylesLoaded, setStylesLoaded] = useState(false);
   const { ToastManager } = window.__NR1_SDK__;
 
@@ -99,23 +99,23 @@ const ComponentPreview = ({ className, style, useToastManager }) => {
       />
       <style type="text/css">{EXAMPLE_CSS}</style>
       {useToastManager && (
-        <div className="nr1-ComponentExample-ToastManager">
+        <div className="nr1-ReferenceExample-ToastManager">
           <ToastManager />
         </div>
       )}
       {stylesLoaded ? (
-        <LivePreview className="nr1-ComponentExample" style={style} />
+        <LivePreview className="nr1-ReferenceExample" style={style} />
       ) : (
         'Loading...'
       )}
     </root.div>
   );
 };
 
-ComponentPreview.propTypes = {
+ReferencePreview.propTypes = {
   className: PropTypes.string,
   style: PropTypes.object,
   useToastManager: PropTypes.bool,
 };
 
-export default ComponentPreview;
+export default ReferencePreview;

src/data/sidenav.json

@@ -348,6 +348,14 @@
       {
         "displayName": "PlatformStateContext",
         "url": "/components/platform-state-context"
+      },
+      {
+        "displayName": "logger",
+        "url": "/apis/logger"
+      },
+      {
+        "displayName": "nerdlet",
+        "url": "/apis/nerdlet"
       }
     ]
   }

src/hooks/useApiDoc.js

@@ -0,0 +1,49 @@
+import { useMemo } from 'react';
+
+const IGNORED_METHODS = [
+  'prototype',
+  'length',
+  'name',
+  'propTypes',
+  'getDerivedStateFromProps',
+  'defaultProps',
+];
+
+const useApiDoc = (name) => {
+  if (typeof window === 'undefined') global.window = {};
+
+  return useMemo(() => {
+    const sdk = window.__NR1_SDK__?.default ?? {};
+    const api = sdk[name];
+
+    if (!api) {
+      return null;
+    }
+
+    const apiDocs = api?.__docs__;
+
+    return {
+      description: apiDocs?.text,
+      usage: `import { ${name} } from 'nr1'`,
+      methods: Object.getOwnPropertyNames(api)
+        .filter(
+          (member) =>
+            !IGNORED_METHODS.includes(member) &&
+            typeof api[member] === 'function'
+        )
+        .map((member) => {
+          const methodDocs = api[member].__docs__;
+
+          return {
+            name: `${name}.${member}`,
+            description: methodDocs?.text,
+            returnValue: methodDocs?.tags.return?.[0] ?? { type: 'undefined' },
+            params: methodDocs?.tags.param ?? [],
+            examples: methodDocs?.tags.examples ?? [],
+          };
+        }),
+    };
+  }, [name, window?.__NR1_SDK__]);
+};
+
+export default useApiDoc;

src/hooks/useComponentDoc.js

@@ -209,6 +209,7 @@ const useComponentDoc = (componentName) => {
             description: methodDocs?.text,
             returnValue: methodDocs?.tags.return?.[0] ?? { type: 'undefined' },
             params: methodDocs?.tags.param ?? [],
+            examples: methodDocs?.tags.examples ?? [],
           };
         }),
     };

src/markdown-pages/apis/logger.mdx

@@ -0,0 +1,7 @@
+---
+path: '/apis/logger'
+title: 'PlatformStateContext'
+description: 'A logger component!'
+api: 'logger'
+template: 'ApiReferenceTemplate'
+---

src/markdown-pages/apis/nerdlet.mdx

@@ -0,0 +1,7 @@
+---
+path: '/apis/nerdlet'
+title: 'Nerdlet'
+description: 'The nerdlet API'
+api: 'nerdlet'
+template: 'ApiReferenceTemplate'
+---

src/markdown-pages/components/account-picker.mdx

@@ -3,5 +3,5 @@ path: '/components/account-picker'
 title: 'AccountPicker'
 description: 'An AccountPicker component!'
 component: 'AccountPicker'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/account-storage-mutation.mdx

@@ -3,5 +3,5 @@ path: '/components/account-storage-mutation'
 title: 'AccountStorageMutation'
 description: 'An AccountStorageMutation component!'
 component: 'AccountStorageMutation'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/account-storage-query.mdx

@@ -3,5 +3,5 @@ path: '/components/account-storage-query'
 title: 'AccountStorageQuery'
 description: 'An AccountStorageQuery component!'
 component: 'AccountStorageQuery'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/accounts-query.mdx

@@ -3,5 +3,5 @@ path: '/components/accounts-query'
 title: 'AccountsQuery'
 description: 'A AccountsQuery component!'
 component: 'AccountsQuery'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/area-chart.mdx

@@ -3,5 +3,5 @@ path: '/components/area-chart'
 title: 'AreaChart'
 description: 'An AreaChart component!'
 component: 'AreaChart'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/auto-sizer.mdx

@@ -3,5 +3,5 @@ path: '/components/auto-sizer'
 title: 'AutoSizer'
 description: 'An AutoSizer component!'
 component: 'AutoSizer'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/bar-chart.mdx

@@ -3,5 +3,5 @@ path: '/components/bar-chart'
 title: 'BarChart'
 description: 'A BarChart component!'
 component: 'BarChart'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/billboard-chart.mdx

@@ -3,5 +3,5 @@ path: '/components/billboard-chart'
 title: 'BillboardChart'
 description: 'A BillboardChart component!'
 component: 'BillboardChart'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/block-text.mdx

@@ -3,5 +3,5 @@ path: '/components/block-text'
 title: 'BlockText'
 description: 'A BlockText component!'
 component: 'BlockText'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/button.mdx

@@ -3,5 +3,5 @@ path: '/components/button'
 title: 'Button'
 description: 'A button component!'
 component: 'Button'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/card-body.mdx

@@ -3,5 +3,5 @@ path: '/components/card-body'
 title: 'CardBody'
 description: 'A CardBody component!'
 component: 'CardBody'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/card-header.mdx

@@ -3,5 +3,5 @@ path: '/components/card-header'
 title: 'CardHeader'
 description: 'A CardHeader component!'
 component: 'CardHeader'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/card.mdx

@@ -3,5 +3,5 @@ path: '/components/card'
 title: 'Card'
 description: 'A Card component!'
 component: 'Card'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/chart-group.mdx

@@ -3,5 +3,5 @@ path: '/components/chart-group'
 title: 'ChartGroup'
 description: 'A ChartGroup component!'
 component: 'ChartGroup'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/checkbox.mdx

@@ -3,5 +3,5 @@ path: '/components/checkbox'
 title: 'Checkbox'
 description: 'A Checkbox component!'
 component: 'Checkbox'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/dropdown-item.mdx

@@ -3,5 +3,5 @@ path: '/components/dropdown-item'
 title: 'DropdownItem'
 description: 'A DropdownItem component!'
 component: 'DropdownItem'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/dropdown.mdx

@@ -3,5 +3,5 @@ path: '/components/dropdown'
 title: 'Dropdown'
 description: 'A Dropdown component!'
 component: 'Dropdown'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/entities-by-domain-type-query.mdx

@@ -3,5 +3,5 @@ path: '/components/entities-by-domain-type-query'
 title: 'EntitiesByDomainTypeQuery'
 description: 'An EntitiesByDomainTypeQuery component!'
 component: 'EntitiesByDomainTypeQuery'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/entities-by-guids-query.mdx

@@ -3,5 +3,5 @@ path: '/components/entities-by-guids-query'
 title: 'EntitiesByGuidsQuery'
 description: 'An EntitiesByGuidsQuery component!'
 component: 'EntitiesByGuidsQuery'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/entities-by-name-query.mdx

@@ -3,5 +3,5 @@ path: '/components/entities-by-name-query'
 title: 'EntitiesByNameQuery'
 description: 'An EntitiesByNameQuery component!'
 component: 'EntitiesByNameQuery'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---

src/markdown-pages/components/entity-by-guid-query.mdx

@@ -3,5 +3,5 @@ path: '/components/entity-by-guid-query'
 title: 'EntityByGuidQuery'
 description: 'An EntityByGuidQuery component!'
 component: 'EntityByGuidQuery'
-template: 'ReferenceTemplate'
+template: 'ComponentReferenceTemplate'
 ---