Merge pull request #824 from iterative/gf-fix_#670

[WIP] Add interactive button to run get-started/ tutorials as Google Colabs, Katacoda, Kaggle kernels, etc. #670
iterative · Dec 4, 2019 · 803cc71 · 803cc71
2 parents cc97843 + df33363
commit 803cc71
Show file tree

Hide file tree

Showing 10 changed files with 217 additions and 22 deletions.
diff --git a/package.json b/package.json
@@ -31,6 +31,7 @@
     "lodash.kebabcase": "^4.1.1",
     "lodash.startcase": "^4.4.0",
     "lodash.throttle": "^4.1.1",
+    "lodash.topairs": "^4.3.0",
     "next": "^9.1.4",
     "perfect-scrollbar": "^1.4.0",
     "prop-types": "^15.7.2",

diff --git a/pages/doc.js b/pages/doc.js
@@ -176,7 +176,7 @@ export default class Documentation extends Component {
 
   render() {
     const {
-      currentItem: { source, path, label, next, prev },
+      currentItem: { source, path, label, tutorials, next, prev },
       headings,
       markdown,
       pageNotFound,
@@ -220,12 +220,17 @@ export default class Documentation extends Component {
             <Markdown
               markdown={markdown}
               githubLink={githubLink}
+              tutorials={tutorials}
               prev={prev}
               next={next}
               onNavigate={this.onNavigate}
             />
           )}
-          <RightPanel headings={headings} githubLink={githubLink} />
+          <RightPanel
+            headings={headings}
+            tutorials={tutorials}
+            githubLink={githubLink}
+          />
         </Container>
       </Page>
     )

diff --git a/src/Documentation/Markdown/Markdown.js b/src/Documentation/Markdown/Markdown.js
@@ -3,6 +3,7 @@ import PropTypes from 'prop-types'
 // components
 import ReactMarkdown from 'react-markdown'
 import { LightButton } from '../LightButton'
+import Tutorials from '../Tutorials'
 import Tooltip from '../../Tooltip'
 import Collapsible from 'react-collapsible'
 // syntax highlighter
@@ -175,11 +176,23 @@ export default class Markdown extends React.PureComponent {
   }
 
   render() {
-    const { markdown, githubLink, prev, next, onNavigate } = this.props
+    const {
+      markdown,
+      githubLink,
+      tutorials,
+      prev,
+      next,
+      onNavigate
+    } = this.props
 
     return (
       <Content id="markdown-root">
-        <GithubLink href={githubLink} target="_blank">
+        {tutorials && (
+          <TutorialsWrapper>
+            <Tutorials tutorials={tutorials} compact={true} />
+          </TutorialsWrapper>
+        )}
+        <GithubLink href={githubLink} target="_blank" rel="nofollow noopener">
           <i /> Edit on GitHub
         </GithubLink>
         <ReactMarkdown
@@ -213,6 +226,7 @@ export default class Markdown extends React.PureComponent {
 Markdown.propTypes = {
   markdown: PropTypes.string.isRequired,
   githubLink: PropTypes.string.isRequired,
+  tutorials: PropTypes.object,
   prev: PropTypes.string,
   next: PropTypes.string,
   onNavigate: PropTypes.func.isRequired
@@ -368,6 +382,21 @@ const Button = styled.div`
   }
 `
 
+const TutorialsWrapper = styled.div`
+  position: relative;
+  z-index: 1;
+  float: right;
+  margin: 5px 0 0 10px;
+
+  ${media.tablet`
+    margin: 0 0 15px 0;
+  `}
+
+  @media only screen and (min-width: 1200px) {
+    display: none;
+  }
+`
+
 export const GithubLink = styled(LightButton)`
   display: none;
   float: right;

diff --git a/src/Documentation/RightPanel/RightPanel.js b/src/Documentation/RightPanel/RightPanel.js
@@ -2,6 +2,7 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
 import { LightButton } from '../LightButton'
+import Tutorials from '../Tutorials'
 // utils
 import throttle from 'lodash.throttle'
 
@@ -109,33 +110,41 @@ export default class RightPanel extends React.PureComponent {
   }, 100)
 
   render() {
-    const { headings, githubLink } = this.props
+    const { headings, githubLink, tutorials } = this.props
     const { current } = this.state
 
     return (
       <Wrapper>
-        {headings.length ? (
+        {!headings.length && <Spacer />}
+        {headings.length > 0 && (
           <>
             <Header>Content</Header>
             <hr />
-            {headings.map(({ slug, text }, headingIndex) => (
+            {headings.map(({ slug, text }) => (
               <HeadingLink
                 isCurrent={current === slug}
                 level={3}
-                key={`link-${headingIndex}`}
+                key={`link-${slug}`}
                 href={`#${slug}`}
               >
                 {text}
               </HeadingLink>
             ))}
             <br />
           </>
-        ) : (
+        )}
+        {Object.keys(tutorials || {}).length > 0 && (
           <>
-            <Spacer />
+            <Description>
+              <span role="img" aria-label="bug">
+                ▶️
+              </span>{' '}
+              It can be run online
+            </Description>
+            <Tutorials tutorials={tutorials} />
+            <br />
           </>
         )}
-
         <Description>
           <span role="img" aria-label="bug">
             🐛
@@ -173,6 +182,7 @@ RightPanel.propTypes = {
       text: PropTypes.string.isRequired
     })
   ).isRequired,
+  tutorials: PropTypes.object,
   githubLink: PropTypes.string.isRequired
 }
 
@@ -224,19 +234,19 @@ const HeadingLink = styled.a`
   }
 `
 
-const GithubButton = styled(LightButton)`
-  min-width: 120px;
+const ExternalButton = styled(LightButton)`
+  box-sizing: border-box;
+  min-width: 170px;
   margin: 10px 0;
+`
 
+const GithubButton = styled(ExternalButton)`
   i {
     background-image: url(/static/img/github_icon.svg);
   }
 `
 
-const DiscordButton = styled(LightButton)`
-  min-width: 120px;
-  margin: 10px 0;
-
+const DiscordButton = styled(ExternalButton)`
   i {
     background-image: url(/static/img/discord.svg);
     width: 1.2em;

diff --git a/src/Documentation/SidebarMenu/helper.js b/src/Documentation/SidebarMenu/helper.js
@@ -14,6 +14,9 @@ import sidebar from '../sidebar'
     source: "/static/docs/get-started/add-files.md",
     prev: "/doc/get-started/configure",
     next: "/doc/get-started/share-data",
+    tutorials: {
+      katacoda: "https://www.katacoda.com/loodse/courses/docker/docker-02-install"
+    }
     children: []
   }
 */
@@ -74,7 +77,7 @@ function validateRawItem({ slug, source, children }) {
 function normalizeItem({ item, parentPath, resultRef, prevRef }) {
   validateRawItem(item)
 
-  const { label, slug, source } = item
+  const { label, slug, source, tutorials } = item
 
   // If prev item doesn't have source we need to recirsively search for it
   const prevItemWithSource =
@@ -89,6 +92,7 @@ function normalizeItem({ item, parentPath, resultRef, prevRef }) {
     path: PATH_ROOT + parentPath + slug,
     source: source === false ? false : sourcePath,
     label: label ? label : startCase(slug),
+    tutorials: tutorials || {},
     prev,
     next: undefined
   }

diff --git a/src/Documentation/SidebarMenu/helper.test.js b/src/Documentation/SidebarMenu/helper.test.js
@@ -13,6 +13,7 @@ describe('SidebarMenu/helper', () => {
           label: 'Item Name',
           path: '/doc/item-name',
           source: '/static/docs/item-name.md',
+          tutorials: {},
           prev: undefined,
           next: undefined
         }
@@ -31,6 +32,7 @@ describe('SidebarMenu/helper', () => {
           label: 'Item Name',
           path: '/doc/item-name',
           source: '/static/docs/item-name.md',
+          tutorials: {},
           prev: undefined,
           next: undefined
         }
@@ -49,6 +51,7 @@ describe('SidebarMenu/helper', () => {
           label: 'Custom Label',
           path: '/doc/item-name',
           source: '/static/docs/item-name.md',
+          tutorials: {},
           prev: undefined,
           next: undefined
         }
@@ -67,6 +70,37 @@ describe('SidebarMenu/helper', () => {
           label: 'Item Name',
           path: '/doc/item-name',
           source: '/static/docs/item-name/index.md',
+          tutorials: {},
+          prev: undefined,
+          next: undefined
+        }
+      ]
+
+      jest.doMock('../sidebar.json', () => rawData)
+      const sidebarData = require('./helper').default
+
+      expect(sidebarData).toEqual(result)
+    })
+
+    it('Forwards tutorials', () => {
+      const rawData = [
+        {
+          slug: 'item-name',
+          tutorials: {
+            katacoda:
+              'https://www.katacoda.com/loodse/courses/dvc/dvc-01-install'
+          }
+        }
+      ]
+      const result = [
+        {
+          label: 'Item Name',
+          path: '/doc/item-name',
+          source: '/static/docs/item-name.md',
+          tutorials: {
+            katacoda:
+              'https://www.katacoda.com/loodse/courses/dvc/dvc-01-install'
+          },
           prev: undefined,
           next: undefined
         }
@@ -90,13 +124,15 @@ describe('SidebarMenu/helper', () => {
           label: 'Item Name',
           path: '/doc/item-name',
           source: '/static/docs/item-name.md',
+          tutorials: {},
           prev: undefined,
           next: '/doc/item-name/nested-item',
           children: [
             {
               label: 'Nested Item',
               path: '/doc/item-name/nested-item',
               source: '/static/docs/item-name/nested-item.md',
+              tutorials: {},
               prev: '/doc/item-name',
               next: '/doc/item-name/nested-item/subnested-item',
               children: [
@@ -105,6 +141,7 @@ describe('SidebarMenu/helper', () => {
                   path: '/doc/item-name/nested-item/subnested-item',
                   source:
                     '/static/docs/item-name/nested-item/subnested-item.md',
+                  tutorials: {},
                   prev: '/doc/item-name/nested-item',
                   next: undefined
                 }
@@ -130,13 +167,15 @@ describe('SidebarMenu/helper', () => {
           label: 'First Item',
           path: '/doc/first-item',
           source: '/static/docs/first-item.md',
+          tutorials: {},
           prev: undefined,
           next: '/doc/first-item/nested-item',
           children: [
             {
               label: 'Nested Item',
               path: '/doc/first-item/nested-item',
               source: '/static/docs/first-item/nested-item.md',
+              tutorials: {},
               prev: '/doc/first-item',
               next: '/doc/second-item'
             }
@@ -146,6 +185,7 @@ describe('SidebarMenu/helper', () => {
           label: 'Second Item',
           path: '/doc/second-item',
           source: '/static/docs/second-item.md',
+          tutorials: {},
           prev: '/doc/first-item/nested-item',
           next: undefined
         }
@@ -167,20 +207,23 @@ describe('SidebarMenu/helper', () => {
           label: 'First Item',
           path: '/doc/first-item',
           source: '/static/docs/first-item.md',
+          tutorials: {},
           prev: undefined,
           next: '/doc/second-item'
         },
         {
           label: 'Second Item',
           path: '/doc/second-item',
           source: false,
+          tutorials: {},
           prev: '/doc/first-item',
           next: '/doc/second-item/nested-item',
           children: [
             {
               label: 'Nested Item',
               path: '/doc/second-item/nested-item',
               source: '/static/docs/second-item/nested-item.md',
+              tutorials: {},
               prev: '/doc/first-item',
               next: undefined
             }
@@ -210,20 +253,23 @@ describe('SidebarMenu/helper', () => {
           label: 'First Item',
           path: '/doc/first-item',
           source: '/static/docs/first-item.md',
+          tutorials: {},
           prev: undefined,
           next: '/doc/second-item'
         },
         {
           label: 'Second Item',
           path: '/doc/second-item',
           source: false,
+          tutorials: {},
           prev: '/doc/first-item',
           next: '/doc/second-item/nested-item',
           children: [
             {
               label: 'Nested Item',
               path: '/doc/second-item/nested-item',
               source: false,
+              tutorials: {},
               prev: '/doc/first-item',
               next: '/doc/second-item/nested-item/subnested-item',
               children: [
@@ -232,6 +278,7 @@ describe('SidebarMenu/helper', () => {
                   path: '/doc/second-item/nested-item/subnested-item',
                   source:
                     '/static/docs/second-item/nested-item/subnested-item.md',
+                  tutorials: {},
                   prev: '/doc/first-item',
                   next: undefined
                 }
@@ -278,6 +325,7 @@ describe('SidebarMenu/helper', () => {
         label: 'Item Name',
         path: '/doc/item-name',
         source: '/static/docs/item-name.md',
+        tutorials: {},
         prev: undefined,
         next: undefined
       }
@@ -302,6 +350,7 @@ describe('SidebarMenu/helper', () => {
         label: 'Subnested Item',
         path: '/doc/item-name/nested-item/subnested-item',
         source: '/static/docs/item-name/nested-item/subnested-item.md',
+        tutorials: {},
         prev: undefined,
         next: undefined
       }