make all sidebar.json indices optional + bunch of comments and some r…

…efactoring
iterative · Jan 5, 2020 · f981979 · f981979
1 parent 109e451
commit f981979
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 66 deletions.
diff --git a/package.json b/package.json
@@ -5,7 +5,7 @@
   "main": "index.js",
   "scripts": {
     "dev": "node server.js",
-    "dev:debug": "node --inspect server.js",
+    "dev:debug": "node --inspect-brk server.js",
     "build": "next build",
     "test": "jest",
     "start": "NODE_ENV=production node server.js",

diff --git a/public/static/docs/sidebar.json b/public/static/docs/sidebar.json
@@ -139,7 +139,7 @@
       {
         "label": "Contributing",
         "slug": "contributing",
-        "source": "contributing/index.md",
+        "source": false,
         "children": [
           {
             "label": "DVC Core Project",

diff --git a/public/static/docs/user-guide/contributing/index.md b/public/static/docs/user-guide/contributing/index.md
diff --git a/server.js b/server.js
@@ -118,6 +118,7 @@ app.prepare().then(() => {
       // Force 404 response for any inexistent /doc item.
       if (!getItemByPath(pathname)) {
         res.statusCode = 404
+        // NOTE: Assumes the route below will render a 404 page.
       }
 
       // Custom route for all docs

diff --git a/src/utils/sidebar.js b/src/utils/sidebar.js
@@ -27,9 +27,19 @@ const PATH_ROOT = '/doc/'
 const FILE_ROOT = '/static/docs/'
 const FILE_EXTENSION = '.md'
 
-/*
- * Private functions
- */
+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) {
@@ -48,36 +58,16 @@ function findItem(data, targetPath) {
   }
 }
 
-function findChildWithSource(item) {
-  return item.source ? item : findChildWithSource(item.children[0])
-}
-
-function findPrevItemWithSource(data, item) {
-  if (item.source) {
-    return item
-  } else if (item.prev) {
-    const prevItem = findItem(data, item.prev)
+function findPrevItemWithSource(data, ref) {
+  if (ref && ref.source) {
+    return ref
+  } else if (ref && ref.prev) {
+    const prevItem = findItem(data, ref.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")
-  }
-
-  if (isSourceDisabled && (!children || !children.length)) {
-    throw Error(
-      "If you set 'source' to false, you had to add at least one child"
-    )
-  }
-}
-
-/* Normalization */
-
 function normalizeItem({ item, parentPath, resultRef, prevRef }) {
   validateRawItem(item)
 
@@ -145,23 +135,36 @@ function normalizeSidebar({
   return currentResult
 }
 
+function findChildWithSource(item) {
+  return item.source ? item : findChildWithSource(item.children[0])
+}
+
 /*
  * Exports
  */
 
+// Runs at module load time
 const normalizedSidebar = normalizeSidebar({
   data: sidebar,
   parentPath: ''
 })
 
+/**
+ * Finds `path` in sidebar struct
+ * @param {*} path
+ * @uses `normalizedSidebar`
+ */
 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
+
+  // TODO: Refactor this recursive fn into a loop inside `getItemByPath`
+  return findChildWithSource(item)
 }
 
 function getParentsListFromPath(path) {