Merge pull request #61 from facebookexperimental/error-messages

Add better error messages for most common cases

lib/build-files.js

@@ -11,10 +11,22 @@
 
 require("babel-register")({
   babelrc: false,
-  only: [__dirname, process.cwd() + "/core"],  
+  only: [__dirname, process.cwd() + "/core"],
   plugins: [require("./server/translate-plugin.js")],
   presets: ["react", "latest"]
 });
 
+// initial check that required files are present
+const chalk = require("chalk");
+const fs = require("fs");
+const CWD = process.cwd();
+
+if (!fs.existsSync(CWD + "/siteConfig.js")) {
+  console.error(
+    chalk.red("Error: No siteConfig.js file found in website folder!")
+  );
+  process.exit(1);
+}
+
 const generate = require("./server/generate.js");
 generate();

lib/core/nav/HeaderNav.js

@@ -128,6 +128,12 @@ class HeaderNav extends React.Component {
           "-" +
           link.doc;
       }
+      if (!Metadata[id]) {
+        throw new Error(
+          "A headerLink is specified with a document that does not exist. No document exists with id: " +
+            link.doc
+        );
+      }
       href = this.props.config.baseUrl + Metadata[id].permalink;
     } else if (link.page) {
       if (fs.existsSync(CWD + "/pages/en/" + link.page + ".js")) {

lib/server/readCategories.js

@@ -56,7 +56,9 @@ function readCategories(sidebar) {
       if (metadata.next) {
         if (!articles[metadata.next]) {
           throw new Error(
-            "`next: " + metadata.next + "` in " + metadata.id + " doesn't exist"
+            metadata.version
+              ? `Improper sidebars file for version ${metadata.version}. Make sure that all documents with ids specified in this version's sidebar file exist and that no ids are repeated.`
+              : `Improper sidebars.json file. Make sure that documents with the ids specified in sidebars.json exist and that no ids are repeated.`
           );
         }
         previous[articles[metadata.next].id] = metadata.id;

lib/server/readMetadata.js

@@ -32,7 +32,12 @@ if (fs.existsSync(CWD + "/languages.js")) {
 }
 
 function readSidebar() {
-  let allSidebars = require(CWD + "/sidebars.json");
+  let allSidebars;
+  if (fs.existsSync(CWD + "/sidebars.json")) {
+    allSidebars = require(CWD + "/sidebars.json");
+  } else {
+    allSidebars = {};
+  }
   Object.assign(allSidebars, versionFallback.sidebarData());
 
   const order = {};
@@ -155,7 +160,7 @@ function processMetadata(file) {
       metadata.previous = language + "-" + order[id].previous;
     }
   }
-  
+
   return { metadata, rawContent: rawContent };
 }
 

lib/server/server.js

@@ -157,6 +157,10 @@ function execute(port) {
     });
 
     const metadata = Metadata[links[url]];
+    if (!metadata) {
+      next();
+      return;
+    }
     const language = metadata.language;
 
     let file;
@@ -438,7 +442,6 @@ function execute(port) {
     res.send(cssContent);
   });
 
-  /* serve static content first from user folder then from docusaurus */
   app.use(
     siteConfig.baseUrl + "docs/assets/",
     express.static(CWD + "/../docs/assets")

lib/server/versionFallback.js

@@ -20,7 +20,7 @@ const ENABLE_TRANSLATION = fs.existsSync(CWD + "/languages.js");
 
 let versions;
 if (fs.existsSync(CWD + "/versions.json")) {
- versions = require(CWD + "/versions.json");
+  versions = require(CWD + "/versions.json");
 } else {
   versions = [];
 }
@@ -124,7 +124,9 @@ function docVersion(id, req_version) {
       return versions[i];
     }
   }
-  return null;
+  throw new Error(
+    `No document available to use for version ${req_version} of document with id ${id}. Verify that all version files are correct.`
+  );
 }
 
 // returns whether a given file has content that differ from the
@@ -226,7 +228,7 @@ function docData() {
 // return the version of the sidebar to use given a requested version
 function sidebarVersion(req_version) {
   // iterate through versions until a version less than or equal to the requested
-  // is found, then check if that verison has an available file to use
+  // is found, then check if that version has an available file to use
   let requestedFound = false;
   for (let i = 0; i < versions.length; i++) {
     if (versions[i] === req_version) {
@@ -243,7 +245,9 @@ function sidebarVersion(req_version) {
       return versions[i];
     }
   }
-  return null;
+  throw new Error(
+    `No sidebar file available to use for version ${req_version}. Verify that all version files are correct.`
+  );
 }
 
 // return whether or not the current sidebars.json file differs from the

lib/start-server.js

@@ -11,11 +11,23 @@
 
 require("babel-register")({
   babelrc: false,
-  only: [__dirname, process.cwd() + "/core"],  
+  only: [__dirname, process.cwd() + "/core"],
   plugins: [require("./server/translate-plugin.js")],
   presets: ["react", "latest"]
 });
 
+// initial check that required files are present
+const chalk = require("chalk");
+const fs = require("fs");
+const CWD = process.cwd();
+
+if (!fs.existsSync(CWD + "/siteConfig.js")) {
+  console.error(
+    chalk.red("Error: No siteConfig.js file found in website folder!")
+  );
+  process.exit(1);
+}
+
 const program = require("commander");
 
 program.option("--port <number>", "Specify port number").parse(process.argv);

lib/version.js

@@ -13,6 +13,7 @@ const glob = require("glob");
 const fs = require("fs-extra");
 const path = require("path");
 const mkdirp = require("mkdirp");
+const chalk = require("chalk");
 const readMetadata = require("./server/readMetadata.js");
 const versionFallback = require("./server/versionFallback.js");
 
@@ -36,14 +37,14 @@ program
 
 if (typeof version === "undefined") {
   console.error(
-    "No version number specified!\nPass the version you wish to create as an argument.\nEx: 1.0.0"
+    `${chalk.yellow("No version number specified!")}\nPass the version you wish to create as an argument.\nEx: 1.0.0`
   );
   process.exit(1);
 }
 
 if (versions.includes(version)) {
   console.error(
-    "This verison already exists!\nSpecify a new version to create that does not already exist."
+    `${chalk.yellow("This version already exists!")}\nSpecify a new version to create that does not already exist.`
   );
   process.exit(1);
 }
@@ -120,3 +121,5 @@ if (versionFallback.diffLatestSidebar()) {
 // update versions.json file
 versions.unshift(version);
 fs.writeFileSync(CWD + "/versions.json", JSON.stringify(versions, null, 2));
+
+console.log(`${chalk.green("Version " + version + " created!\n")}`);

package.json

@@ -11,6 +11,7 @@
     "babel-register": "^6.24.1",
     "babel-traverse": "^6.25.0",
     "babylon": "^6.17.4",
+    "chalk": "^2.1.0",
     "classnames": "^2.2.5",
     "commander": "^2.11.0",
     "diff": "^3.3.0",