From f981979c18b9854026d0ffefc0a93938d3e07217 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Sat, 4 Jan 2020 18:26:30 -0600 Subject: [PATCH] make all sidebar.json indices optional + bunch of comments and some refactoring --- package.json | 2 +- public/static/docs/sidebar.json | 2 +- .../docs/user-guide/contributing/index.md | 35 ----------- server.js | 1 + src/utils/sidebar.js | 61 ++++++++++--------- 5 files changed, 35 insertions(+), 66 deletions(-) delete mode 100644 public/static/docs/user-guide/contributing/index.md diff --git a/package.json b/package.json index 426f1a9649..475db187e6 100644 --- 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 index 68c3c4d148..c253134e83 100644 --- 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 deleted file mode 100644 index 14b24fe0b6..0000000000 --- a/public/static/docs/user-guide/contributing/index.md +++ /dev/null @@ -1,35 +0,0 @@ -# Contributing - -## Contributing to DVC - -We welcome [contributions](/doc/user-guide/contributing/core) to -[DVC](https://github.com/iterative/dvc) by the community. - -- [How to report a problem](/doc/user-guide/contributing/core#how-to-report-a-problem) - -- [Submitting changes](/doc/user-guide/contributing/core#submitting-changes) - -- [Development environment](/doc/user-guide/contributing/core#development-environment) - -- [Running tests](/doc/user-guide/contributing/core#running-tests) - -- [Testing remotes](/doc/user-guide/contributing/core#testing-remotes) - -- [Code style guidelines (for Python)](/doc/user-guide/contributing/core#code-style-guidelines-for-python) - -- [Commit message format guidelines](/doc/user-guide/contributing/core#commit-message-format-guidelines) - -## Contributing Docs - -We welcome any [contributions](/doc/user-guide/contributing/docs) to our -documentation repository, [dvc.org](https://github.com/iterative/dvc.org). -Contribution can be an update to the documentation or (rare) updating or fixing -the JS engine that we use to run the website. - -- [Structure of the project](/doc/user-guide/contributing/docs#structure-of-the-project) - -- [Submitting changes](/doc/user-guide/contributing/docs#submitting-changes) - -- [Development environment](/doc/user-guide/contributing/docs#development-environment) - -- [Doc style guidelines and tips (for JavaScript and Markdown)](/doc/user-guide/contributing/docs#doc-style-guidelines-and-tips-for-java-script-and-markdown) diff --git a/server.js b/server.js index 8055c2ee8a..7609b42135 100644 --- 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 index 340890b529..97515f7038 100644 --- 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,15 +135,25 @@ 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) @@ -161,7 +161,10 @@ function getItemByPath(path) { ? 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) {