feat(docs): add API Reference links to all platform sections

Author: timmywil

content/docs/iOS/getting-started.md

@@ -111,52 +111,50 @@ The `self` in this example means that `MyViewController` also implements `Spokes
 Now that we have an instance of `Spokestack`, we'll use the [delegate pattern](https://en.wikipedia.org/wiki/Delegation_pattern) so that the ASR, NLU, and TTS features can send events to you. We'll do that in the same class we used in the previous step. All `SpokestackDelegate` functions are optional except for `failure(error:)`, so you will opt in to each one explictly, but for now we just need to use two of them. First, `failure(error:)`:
 
 ```swift
-
-    func failure(error: Error) {
-        print("failure \(String(describing: error))")
-    }
+func failure(error: Error) {
+    print("failure \(String(describing: error))")
+}
 
 ```
 
 This will allow Spokestack modules to communicate back to us if something goes wrong. You may also want to listen for `onInit`, which will tell you when Spokestack is ready to start:
 
 ```swift
-    func onInit() {
-        // ready! time to start listening
-        spokestack.pipeline.start()
-    }
+func onInit() {
+    // ready! time to start listening
+    spokestack.pipeline.start()
+}
 ```
 
 Next, you may not have noticed, but when we built `Spokestack`, we took advantage of a neat feature where Spokestack will automatically classify what the ASR hears. Classifying what your user says into an action in your app is the job of an NLU, or natural language understanding, module. Earlier we configured Spokestack to classify what your user says in terms of guessing a number. Let's wire that up so that we can see what it comes up with!
 
 ```swift
-    func classification(result: NLUResult) {
-        let intent = result.intent
-        let slots = result.slots
-        switch result.intent {
-        // your app picks a number. the user guess a number.
-        case "NumberGuessIntent":
-            let guess = result.slots!["number"]!.value as! Int
-            // if the guess is higher, lower, or equal to the pick, respond accordingly
-            return
-        case "AMAZON.HelpIntent":
-            // if the user asks for help, respond with the rules of the game
-            return
-        case "AMAZON.StopIntent":
-            // If the user wants to stop playing, then pick another number
-            return
-        case default:
-            // what your user said doesn't make sense in terms of a high/low guessing game, so give them a nudge along the right direction
-            return
-        }
+func classification(result: NLUResult) {
+    let intent = result.intent
+    let slots = result.slots
+    switch result.intent {
+    // your app picks a number. the user guess a number.
+    case "NumberGuessIntent":
+        let guess = result.slots!["number"]!.value as! Int
+        // if the guess is higher, lower, or equal to the pick, respond accordingly
+        return
+    case "AMAZON.HelpIntent":
+        // if the user asks for help, respond with the rules of the game
+        return
+    case "AMAZON.StopIntent":
+        // If the user wants to stop playing, then pick another number
+        return
+    case default:
+        // what your user said doesn't make sense in terms of a high/low guessing game, so give them a nudge along the right direction
+        return
     }
+}
 
-    // ...other delegate functions...
-
-    func didTrace(_ trace: String) {
-        // Get Spokestack module tracing messages that provide additional debugging information. Note that tracing verbosity of each is determined by the SpeechConfiguration.tracing setting!
-    }
+// ...other delegate functions...
 
+func didTrace(_ trace: String) {
+    // Get Spokestack module tracing messages that provide additional debugging information. Note that tracing verbosity of each is determined by the SpeechConfiguration.tracing setting!
+}
 ```
 
 You'll note that the intents are just a single string. A intent-based classifier will regularize all sorts of related langague into a single canonical intent, eg "let's go" or "please cease" get classified as `start` and `stop`, respectively.
@@ -170,7 +168,7 @@ If you want full hands-free and eyes-free interaction, you'll want to deliver re
 ```swift
 import AVFoundation
 
-...
+// ...
 
 class MyViewController: UIViewController, SpokestackDelegate {
 
@@ -195,7 +193,7 @@ To play the voice response represented by your input with the default audio syst
 // uses default SpeechConfiguration values for api access.
 let tts = TextToSpeech(self, configuration: SpeechConfiguration())
 
-...
+// ...
 
 func speak(_ text: String) {
     let input = TextToSpeechInput(text)

content/docs/nav.json

@@ -17,6 +17,13 @@
   "TTS (iOS)",
   "Cookbook (iOS)",
   "Tray (iOS)",
+  {
+    "external": true,
+    "href": "https://spokestack.github.io/spokestack-ios/",
+    "navId": "API Reference (iOS)",
+    "section": "iOS",
+    "title": "API Reference"
+  },
   "Overview (Android)",
   "Getting Started (Android)",
   "Spokestack Configuration (Android)",
@@ -25,6 +32,13 @@
   "TTS (Android)",
   "Cookbook (Android)",
   "Tray (Android)",
+  {
+    "external": true,
+    "href": "https://www.javadoc.io/doc/io.spokestack/spokestack-android/latest/index.html",
+    "navId": "API Reference (Android)",
+    "section": "Android",
+    "title": "API Reference"
+  },
   "Overview (react-native)",
   "Getting Started (react-native)",
   "Speech Pipeline (react-native)",
@@ -33,20 +47,40 @@
   "TTS (react-native)",
   "Cookbook (react-native)",
   "Tray (react-native)",
+  {
+    "external": true,
+    "href": "https://github.com/spokestack/react-native-spokestack#readme",
+    "navId": "API Reference (react-native)",
+    "section": "React Native",
+    "title": "API Reference"
+  },
   "Overview (Python)",
   "Getting Started (Python)",
   "Speech Pipeline (Python)",
   "NLU (Python)",
   "TTS (Python)",
+  {
+    "external": true,
+    "href": "https://spokestack.readthedocs.io/en/stable/",
+    "navId": "API Reference (Python)",
+    "section": "Python",
+    "title": "API Reference"
+  },
   "Overview (Node)",
   "Getting Started (Node)",
+  {
+    "external": true,
+    "href": "https://github.com/spokestack/node-spokestack#readme",
+    "navId": "API Reference (Node)",
+    "section": "Node",
+    "title": "API Reference"
+  },
   "Getting Started (Design)",
   "Find the Right Use Case",
   "Map Out Integration",
   "Script Responses",
   "Tips for Designing Visual Output",
   "Tips for Writing Dialogue",
-  "Further Learning",
   "Export (Integrations)",
   "Speech Pipeline Configuration (Machine Learning)",
   "Wake Word Models (Machine Learning)",

src/components/DocsPage.tsx

@@ -1,26 +1,23 @@
 import * as theme from '../styles/theme'
 
-import { PageRendererProps, graphql, useStaticQuery } from 'gatsby'
+import { Global, css } from '@emotion/react'
 import { Mdx, Query } from '../utils/graphql'
-import { MDXRenderer } from 'gatsby-plugin-mdx'
+import { PageRendererProps, graphql, useStaticQuery } from 'gatsby'
+import orderDocsLinks, { DocsLinks } from '../utils/orderDocsLinks'
+
 import Create from './Create'
 import DarkModeButton from '../components/DarkModeButton'
 import Layout from '../components/Layout'
-import React from 'react'
+import { MDXRenderer } from 'gatsby-plugin-mdx'
 import { PageContext } from '../types'
+import React from 'react'
+import Related from './Related'
 import SEO from '../components/SEO'
-import { StickyLink } from '../components/StickyNav'
 import StickyNavLayout from '../components/StickyNavLayout'
-import { css, Global } from '@emotion/react'
-import difference from 'lodash/difference'
 import findImage from '../utils/findImage'
+import hashToId from '../utils/hashToId'
 import { isLoggedIn } from '../utils/auth'
-import order from '../../content/docs/nav.json'
 import removeTrailingSlash from '../utils/removeTrailingSlash'
-import sortBy from 'lodash/sortBy'
-import uniqBy from 'lodash/uniqBy'
-import Related from './Related'
-import hashToId from '../utils/hashToId'
 
 interface Props {
   location: PageRendererProps['location']
@@ -29,53 +26,34 @@ interface Props {
   selectFirst?: boolean
 }
 
-function checkDups(links: StickyLink[]) {
-  const unique = uniqBy(links, (link) => link.navId)
-  if (unique.length !== links.length) {
-    const diff = difference(links, unique)
-    throw new Error(
-      `The following navIds are not unique: ${diff
-        .map((link) => link.navId)
-        .join(', ')}.`
-    )
-  }
-}
-
-function orderLinks(links: StickyLink[]) {
-  checkDups(links)
-  return sortBy(links, (link) => {
-    const index = order.indexOf(link.navId)
-    if (index === -1) {
-      throw new Error(
-        `Docs page with title ${link.title} has navId ${link.navId}, which does not exist in nav.json.`
-      )
-    }
-    return index
-  })
-}
-
 export default function DocsPage({
   location,
   post,
   related,
   selectFirst
 }: Props) {
-  const links: StickyLink[] = []
+  const links: DocsLinks = {}
   const data = useStaticQuery<Query>(docsPageQuery)
   const posts = data.allMdx.edges
   posts.forEach(({ node }) => {
     const fields = node.fields!
     const frontmatter = node.frontmatter!
     const title = frontmatter.title!
-    links.push({
+    const navId = frontmatter.navId!
+    if (links[navId] != null) {
+      throw new Error(
+        `The navId "${navId}" is not unique. Ensure only one doc has this navId.`
+      )
+    }
+    links[navId] = {
       href: fields.slug!,
       section: fields.folder!,
       title,
-      navId: frontmatter.navId!,
+      navId,
       navTitle: frontmatter.navTitle || title
-    })
+    }
   })
-  const orderedLinks = orderLinks(links)
+  const orderedLinks = orderDocsLinks(links)
   if (selectFirst) {
     orderedLinks[0].forceSelect = true
   }

src/components/StickyNavSection.tsx

@@ -3,14 +3,16 @@ import * as theme from '../styles/theme'
 import { Global, css } from '@emotion/react'
 import React, { MutableRefObject, useState } from 'react'
 
+import Color from 'color'
 import SVGIcon from './SVGIcon'
 import type { WindowLocation } from '@reach/router'
 import currentPath from '../utils/currentPath'
 import getHash from '../utils/getHash'
 import hashToId from '../utils/hashToId'
-import Color from 'color'
 
 export interface StickyLink {
+  // Specifies an external link
+  external?: boolean
   forceSelect?: boolean
   href: string
   matchHash?: boolean
@@ -65,8 +67,12 @@ export default function StickyNavSection({
 
           html.dark-mode {
             .sticky-nav-link,
-            .sticky-nav-link:visited {
+            .sticky-nav-link:visited:not(:hover) {
               color: ${Color('#ffffff').fade(0.2).toString()};
+
+              .icon {
+                fill: ${Color('#ffffff').fade(0.2).toString()};
+              }
             }
             .nav-selected-bg,
             .sticky-nav-link.active {
@@ -130,6 +136,13 @@ export default function StickyNavSection({
               href={link.href}
               title={link.title}>
               {link.navTitle || link.title}
+              {link.external && (
+                <SVGIcon
+                  icon="#external"
+                  className="icon"
+                  extraCss={styles.externalIcon}
+                />
+              )}
             </a>
           )
         })}
@@ -182,23 +195,40 @@ const styles = {
     }
   `,
   stickyNavLink: css`
+    display: flex;
+    flex-direction: row;
+    justify-content: flex-start;
+    align-items: center;
     line-height: 1.2;
     padding: 12px 20px 12px 22px;
     text-decoration: none;
     user-select: none;
     font-size: 14px;
 
     &,
-    &:visited {
+    &:visited:not(:hover) {
       color: ${theme.headerColor.fade(0.25).toString()};
+
+      .icon {
+        fill: ${theme.headerColor.fade(0.25).toString()};
+      }
     }
     &:hover {
       color: ${theme.linkHover};
+
+      .icon {
+        fill: ${theme.linkHover};
+      }
     }
     &.active,
     &.active-no-bg {
       cursor: default;
       pointer-events: none;
     }
+  `,
+  externalIcon: css`
+    width: 10px;
+    height: 10px;
+    margin-left: 7px;
   `
 }