cmd ref: remove unnecessary indices?

.gitignore

@@ -17,9 +17,6 @@ lib-cov
 # Coverage directory used by tools like istanbul
 coverage
 
-# nyc test coverage
-.nyc_output
-
 # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
 .grunt
 

package.json

@@ -5,7 +5,7 @@
   "main": "index.js",
   "scripts": {
     "dev": "node server.js",
-    "dev:debug": "node --inspect server.js",
+    "debug": "node --inspect-brk server.js",
     "build": "next build",
     "test": "jest",
     "start": "NODE_ENV=production node server.js",

pages/doc.js

@@ -60,7 +60,7 @@ export default function Documentation({ item, headings, markdown, errorCode }) {
           apiKey: '755929839e113a981f481601c4f52082',
           indexName: 'dvc',
           inputSelector: '#doc-search',
-          debug: false // Set debug to true if you want to inspect the dropdown
+          debug: false // Set to `true` if you want to inspect the dropdown
         })
       }
     } catch (ReferenceError) {

public/static/docs/sidebar.json

@@ -30,7 +30,6 @@
     ]
   },
   {
-    "label": "Install",
     "slug": "install",
     "source": "install/index.md",
     "children": [
@@ -53,7 +52,7 @@
   },
   {
     "slug": "tutorials",
-    "source": "tutorials/index.md",
+    "source": false,
     "children": [
       {
         "slug": "interactive",
@@ -140,7 +139,7 @@
       {
         "label": "Contributing",
         "slug": "contributing",
-        "source": "contributing/index.md",
+        "source": false,
         "children": [
           {
             "label": "DVC Core Project",
@@ -356,8 +355,8 @@
     ]
   },
   {
-    "label": "Understanding DVC",
     "slug": "understanding-dvc",
+    "label": "Understanding DVC",
     "source": false,
     "children": [
       "collaboration-issues",

public/static/docs/user-guide/contributing/docs.md

@@ -89,8 +89,8 @@ documentation files automatically.
 
 ### Debugging
 
-The `yarn dev:debug` script runs the local development server with Node's
-[`--inspect` option](https://nodejs.org/en/docs/guides/debugging-getting-started/#command-line-options)
+The `yarn debug` script runs the local development server with `node`'s
+[`--inspect-brk` option](https://nodejs.org/en/docs/guides/debugging-getting-started/#command-line-options)
 in order for debuggers to connect to it (on the default port, 9229).
 
 > For example, use this launch configuration in **Visual Studio Code**:
@@ -101,7 +101,7 @@ in order for debuggers to connect to it (on the default port, 9229).
 >   "request": "launch",
 >   "name": "Launch via Yarn",
 >   "runtimeExecutable": "yarn",
->   "runtimeArgs": ["dev:debug"],
+>   "runtimeArgs": ["debug"],
 >   "port": 9229
 > }
 > ```

server.js

@@ -1,9 +1,13 @@
 /* eslint-env node */
 
-// This file doesn't go through babel or webpack transformation. Make sure the
-// syntax and sources this file requires are compatible with the current Node.js
-// version you are running. (See https://github.com/zeit/next.js/issues/1245 for
-// discussions on universal Webpack vs universal Babel.)
+/*
+ * Custom server (with custom routes) See
+ * https://nextjs.org/docs/advanced-features/custom-server
+ *
+ * NOTE: This file doesn't go through babel or webpack. Make sure the syntax and
+ * sources this file requires are compatible with the current node version you
+ * are running.
+ */
 
 const { createServer } = require('http')
 const next = require('next')
@@ -21,7 +25,7 @@ app.prepare().then(() => {
     const { pathname, query } = parsedUrl
 
     /*
-     * Special URL redirects.
+     * HTTP redirects
      * NOTE: The order of the redirects is important.
      */
     if (
@@ -107,22 +111,21 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/doc(\/.*)?$/.test(pathname)) {
       /*
-       * Special Docs Engine handler
+       * Docs Engine handler
        */
 
-      // Force 404 response for any inexistent /doc item.
+      // Force 404 response code for any inexistent /doc item.
       if (!getItemByPath(pathname)) {
         res.statusCode = 404
       }
 
-      // Fire up docs engine!
+      // Custom route for all docs
       app.render(req, res, '/doc', query)
     } else {
       // Regular Next handler
       handle(req, res, parsedUrl)
     }
   }).listen(port, err => {
-    // Invokes `createServer` server.
     if (err) throw err
     console.info(`> Ready on localhost:${port}`)
   })

src/utils/sidebar.js

@@ -1,11 +1,7 @@
 /* eslint-env node */
-
-const startCase = require('lodash.startcase')
-const sidebar = require('../../public/static/docs/sidebar.json')
-
 /*
-  We will use this helper to normalize sidebar structure and create
-  all of the resurces we need to prevent future recalculations.
+  These helpers normalize sidebar structure and create all the resources needed.
+  This prevents future recalculations.
 
   Target structure example:
 
@@ -22,11 +18,26 @@ const sidebar = require('../../public/static/docs/sidebar.json')
   }
 */
 
+const startCase = require('lodash.startcase')
+const sidebar = require('../../public/static/docs/sidebar.json')
+
 const PATH_ROOT = '/doc/'
 const FILE_ROOT = '/static/docs/'
 const FILE_EXTENSION = '.md'
 
-// Inner helpers
+function validateRawItem({ slug, source, children }) {
+  const isSourceDisabled = source === false
+
+  if (!slug) {
+    throw Error("'slug' field is required in objects in sidebar.json")
+  }
+
+  if (isSourceDisabled && (!children || !children.length)) {
+    throw Error(
+      "If you set 'source' to false, you had to add at least one child"
+    )
+  }
+}
 
 function findItem(data, targetPath) {
   if (data.length) {
@@ -45,42 +56,22 @@ function findItem(data, targetPath) {
   }
 }
 
-function findChildWithSource(item) {
-  return item.source ? item : findChildWithSource(item.children[0])
-}
-
 function findPrevItemWithSource(data, item) {
-  if (item.source) {
+  if (item && item.source) {
     return item
-  } else if (item.prev) {
+  } else if (item && item.prev) {
     const prevItem = findItem(data, item.prev)
 
     return findPrevItemWithSource(data, prevItem)
   }
 }
 
-function validateRawItem({ slug, source, children }) {
-  const isSourceDisabled = source === false
-
-  if (!slug) {
-    throw Error("'slug' field is required in objects in sidebar.json")
-  }
+function normalizeItem({ rawItem, parentPath, resultRef, prevRef }) {
+  validateRawItem(rawItem)
 
-  if (isSourceDisabled && (!children || !children.length)) {
-    throw Error(
-      "If you set 'source' to false, you had to add at least one child"
-    )
-  }
-}
+  const { label, slug, source, tutorials } = rawItem
 
-// Normalization
-
-function normalizeItem({ item, parentPath, resultRef, prevRef }) {
-  validateRawItem(item)
-
-  const { label, slug, source, tutorials } = item
-
-  // If prev item doesn't have source we need to recirsively search for it
+  // If prev item doesn't have source we need to search for it
   const prevItemWithSource =
     prevRef && findPrevItemWithSource(resultRef, prevRef)
 
@@ -111,9 +102,9 @@ function normalizeSidebar({
 
   data.forEach(rawItem => {
     const isShortcut = typeof rawItem === 'string'
-    const item = isShortcut ? { slug: rawItem } : rawItem
+    rawItem = isShortcut ? { slug: rawItem } : rawItem
     const normalizedItem = normalizeItem({
-      item,
+      rawItem,
       parentPath,
       resultRef,
       prevRef
@@ -123,10 +114,10 @@ function normalizeSidebar({
       prevRef.next = normalizedItem.path
     }
 
-    if (item.children) {
+    if (rawItem.children) {
       normalizedItem.children = normalizeSidebar({
-        data: item.children,
-        parentPath: `${parentPath}${item.slug}/`,
+        data: rawItem.children,
+        parentPath: `${parentPath}${rawItem.slug}/`,
         parentResultRef: resultRef,
         startingPrevRef: normalizedItem
       })
@@ -142,21 +133,29 @@ function normalizeSidebar({
   return currentResult
 }
 
+function findChildWithSource(item) {
+  return item.source ? item : findChildWithSource(item.children[0])
+}
+
+/*
+ * Exports
+ */
+
 const normalizedSidebar = normalizeSidebar({
   data: sidebar,
   parentPath: ''
 })
 
-// Exports
-
 function getItemByPath(path) {
   const normalizedPath = path.replace(/\/$/, '')
   const isRoot = normalizedPath === PATH_ROOT.slice(0, -1)
   const item = isRoot
     ? normalizedSidebar[0]
     : findItem(normalizedSidebar, normalizedPath)
 
-  return item && findChildWithSource(item)
+  if (!item) return false
+
+  return findChildWithSource(item)
 }
 
 function getParentsListFromPath(path) {

src/utils/sidebar.test.js

@@ -336,20 +336,31 @@ describe('SidebarMenu/helper', () => {
       expect(getItemByPath('/doc')).toEqual(result)
     })
 
-    it('Returns first child with source for sourceless parents', () => {
+    // eslint-disable-next-line max-len
+    it('Returns first child with source for all parents with source:false', () => {
       const rawData = [
         {
-          slug: 'item-name',
+          slug: 'item',
           source: false,
           children: [
-            { slug: 'nested-item', source: false, children: ['subnested-item'] }
+            {
+              slug: 'nested',
+              source: false,
+              children: [
+                {
+                  slug: 'subnested',
+                  source: false,
+                  children: ['leaf-item']
+                }
+              ]
+            }
           ]
         }
       ]
       const result = {
-        label: 'Subnested Item',
-        path: '/doc/item-name/nested-item/subnested-item',
-        source: '/static/docs/item-name/nested-item/subnested-item.md',
+        label: 'Leaf Item',
+        path: '/doc/item/nested/subnested/leaf-item',
+        source: '/static/docs/item/nested/subnested/leaf-item.md',
         tutorials: {},
         prev: undefined,
         next: undefined
@@ -358,7 +369,9 @@ describe('SidebarMenu/helper', () => {
       jest.doMock('../../public/static/docs/sidebar.json', () => rawData)
       const { getItemByPath } = require('./sidebar')
 
-      expect(getItemByPath('/doc/item-name')).toEqual(result)
+      expect(getItemByPath('/doc/item')).toEqual(result)
+      expect(getItemByPath('/doc/item/nested')).toEqual(result)
+      expect(getItemByPath('/doc/item/nested/subnested')).toEqual(result)
     })
   })