Merge pull request #109 from webdoc-labs/feature/tutorials

Feature: Tutorials

Author: ShukantPal

common/config/rush/command-line.json

@@ -13,66 +13,66 @@
   "commands": [
     {
       "commandKind": "bulk",
-    
+
       "name": "unit-test",
       "summary": "Runs Unit Tests for all packages",
       "description": "This will run all the unit tests that are defined within each package.json.\nScript name should be 'unit-tests'",
-    
+
       "safeForSimultaneousRushProcesses": false,
       "enableParallelism": false,
       "ignoreDependencyOrder": false,
       "ignoreMissingScript": false,
-    
+
       "allowWarningsInSuccessfulBuild": true
     },
     {
       "commandKind": "bulk",
-    
+
       "name": "lint",
       "summary": "Lints all packages",
       "description": "This will run linting on all packages that have a `lint` script defined.",
-    
+
       "safeForSimultaneousRushProcesses": false,
       "enableParallelism": true,
       "ignoreDependencyOrder": true,
       "ignoreMissingScript": true,
-    
+
       "allowWarningsInSuccessfulBuild": false
     },
     {
       "commandKind": "bulk",
-    
+
       "name": "flow",
       "summary": "Runs flow on all packages",
       "description": "This will run flow type checking on all packages that have a `flow` script defined.",
       "safeForSimultaneousRushProcesses": false,
       "enableParallelism": true,
       "ignoreDependencyOrder": true,
       "ignoreMissingScript": true,
-    
+
       "allowWarningsInSuccessfulBuild": false
     }
-    // 
+    //
     // {
     //   /**
     //    * (Required) Determines the type of custom command.
     //    * Rush's "global" commands are invoked once for the entire repo.
     //    */
     //   "commandKind": "global",
-    // 
+    //
     //   "name": "my-global-command",
     //   "summary": "Example global custom command",
     //   "description": "This is an example custom command that runs once for the entire repo",
-    // 
+    //
     //   "safeForSimultaneousRushProcesses": false,
-    // 
+    //
     //   /**
     //    * (Required) A script that will be invoked using the OS shell. The working directory will be
     //    * the folder that contains rush.json.  If custom parameters are associated with this command, their
     //    * values will be appended to the end of this string.
     //    */
     //   "shellCommand": "node common/scripts/my-global-command.js",
-    // 
+    //
     //   /**
     //    * If your "shellCommand" script depends on NPM packages, the recommended best practice is
     //    * to make it into a regular Rush project that builds using your normal toolchain.  In cases where
@@ -106,12 +106,12 @@
     //    * A "flag" is a custom command-line parameter whose presence acts as an on/off switch.
     //    */
     //   "parameterKind": "flag",
-    // 
+    //
     //   /**
     //    * (Required) The long name of the parameter.  It must be lower-case and use dash delimiters.
     //    */
     //   "longName": "--my-flag",
-    // 
+    //
     //   /**
     //    * An optional alternative short name for the parameter.  It must be a dash followed by a single
     //    * lower-case or upper-case letter, which is case-sensitive.
@@ -122,22 +122,22 @@
     //    * a short name if you expect the parameter to be needed very often in everyday operations.
     //    */
     //   "shortName": "-m",
-    // 
+    //
     //   /**
     //    * (Required) A long description to be shown in the command-line help.
     //    *
     //    * Whenever you introduce commands/parameters, taking a little time to write meaningful
     //    * documentation can make a big difference for the developer experience in your repo.
     //    */
     //   "description": "A custom flag parameter that is passed to the scripts that are invoked when building projects",
-    // 
+    //
     //   /**
     //    * (Required) A list of custom commands and/or built-in Rush commands that this parameter may
     //    * be used with.  The parameter will be appended to the shell command that Rush invokes.
     //    */
     //   "associatedCommands": ["build", "rebuild"]
     // },
-    // 
+    //
     // {
     //   /**
     //    * (Required) Determines the type of custom parameter.
@@ -146,9 +146,9 @@
     //   "parameterKind": "string",
     //   "longName": "--my-string",
     //   "description": "A custom string parameter for the \"my-global-command\" custom command",
-    // 
+    //
     //   "associatedCommands": ["my-global-command"],
-    // 
+    //
     //   /**
     //    * The name of the argument, which will be shown in the command-line help.
     //    *
@@ -157,13 +157,13 @@
     //    * be comprised of upper-case letters, numbers, and underscores.  It should be kept short.
     //    */
     //   "argumentName": "SOME_TEXT",
-    // 
+    //
     //   /**
     //    * If true, this parameter must be included with the command.  The default is false.
     //    */
     //   "required": false
     // },
-    // 
+    //
     // {
     //   /**
     //    * (Required) Determines the type of custom parameter.
@@ -173,22 +173,22 @@
     //   "parameterKind": "choice",
     //   "longName": "--my-choice",
     //   "description": "A custom choice parameter for the \"my-global-command\" custom command",
-    // 
+    //
     //   "associatedCommands": ["my-global-command"],
-    // 
+    //
     //   /**
     //    * If true, this parameter must be included with the command.  The default is false.
     //    */
     //   "required": false,
-    // 
+    //
     //   /**
     //    * Normally if a parameter is omitted from the command line, it will not be passed
     //    * to the shell command. this value will be inserted by default.  Whereas if a "defaultValue"
     //    * is defined, the parameter will always be passed to the shell command, and will use the
     //    * default value if unspecified.  The value must be one of the defined alternatives.
     //    */
     //   "defaultValue": "vanilla",
-    // 
+    //
     //   /**
     //    * (Required) A list of alternative argument values that can be chosen for this parameter.
     //    */
@@ -199,7 +199,7 @@
     //        * e.g. "vanilla" in "--flavor vanilla".
     //        */
     //       "name": "vanilla",
-    // 
+    //
     //       /**
     //        * A detailed description for the alternative that can be shown in the command-line help.
     //        *
@@ -208,12 +208,12 @@
     //        */
     //       "description": "Use the vanilla flavor (the default)"
     //     },
-    // 
+    //
     //     {
     //       "name": "chocolate",
     //       "description": "Use the chocolate flavor"
     //     },
-    // 
+    //
     //     {
     //       "name": "strawberry",
     //       "description": "Use the strawberry flavor"

example/package.json

@@ -27,7 +27,7 @@
     "build-next": "cd .. && webdoc && cd example",
     "build-pixi-api": "cd ../../pixi-api && webdoc && cd ../webdoc/example",
     "build-pixi-api-prod": "cd ../../pixi-api && webdoc --site-root pixi-api && cd ../webdoc/example",
-    "build-pixi-api-gcp": "cd ../../pixi-api && webdoc && cd ../webdoc/example"
+    "build-pixi-api-gcp": "cd ../../pixi-api && webdoc --tutorials ./projects/guides --verbose && cd ../webdoc/example"
   },
   "bugs": {
     "url": "https://github.com/SukantPal/webdoc/issues"

packages/webdoc-cli/README.md

@@ -18,6 +18,7 @@ npm install --save-dev @webdoc/cli
 generate the `sitemap.xml`. This is useful if you want to integrate with [Algolia and use its crawler](https://www.algolia.com/products/crawler/). You must include the protocol for this to work currently, e.g. `http://pixijs.webdoclabs.com`.
 * `--site-root <path>`: If using absolute links in a template, this will set the basepath. The basepath should the directory in which the documentation is being stored relative to where the server is running. The site root is "/" by default - which means that you'll need to serve the documentation directory as top-level. Note that @webdoc/default-template uses absolute links.
 * `-c <config-path>`: This sets the path of the configuration file webdoc uses.
+* `-u <tutorials-directory>` -  (optional) This should point to a directory containing tutorials written in Markdown (".md") or HTML ".html, ".htm". JSON files can be used to configure the hierarchy and naming of tutorials (see the Tutorial Configuration section).
 
 ### Configuration
 
@@ -90,21 +91,23 @@ The `template` object is used by the site template.
 
 ```json
 {
-  "applicationName": "{ <i>webdoc</i> }",
-  "meta": {
-    "og:title": "webdoc",
-    "og:description": "webdoc API documentation",
-    "og:image": "https://camo.githubusercontent.com/1427d2fdabd8790c93ca05cbfb653e2c6a8ab5694e671a04aa3af3fcef313539/68747470733a2f2f692e6962622e636f2f5a4850395044382f4c6f676f2d4672616d652d352e706e67",
-    "og:url": "{{url}}",
-    "og:site_name": "webdoclabs.com"
-  },
-  "repository": "http://github.com/webdoc-labs/webdoc",
-  "integrations": {
-    "search": {
-      "provider": "algolia",
-      "apiKey": "kadlfj232983lkqwem",
-      "indexName": "webdoc-example",
-      "appId": "349o39841;akdsfu"
+  "template": {
+    "applicationName": "{ <i>webdoc</i> }",
+    "meta": {
+      "og:title": "webdoc",
+      "og:description": "webdoc API documentation",
+      "og:image": "https://camo.githubusercontent.com/1427d2fdabd8790c93ca05cbfb653e2c6a8ab5694e671a04aa3af3fcef313539/68747470733a2f2f692e6962622e636f2f5a4850395044382f4c6f676f2d4672616d652d352e706e67",
+      "og:url": "{{url}}",
+      "og:site_name": "webdoclabs.com"
+    },
+    "repository": "http://github.com/webdoc-labs/webdoc",
+    "integrations": {
+      "search": {
+        "provider": "algolia",
+        "apiKey": "kadlfj232983lkqwem",
+        "indexName": "webdoc-example",
+        "appId": "349o39841;akdsfu"
+      }
     }
   }
 }
@@ -117,3 +120,107 @@ The `template` object is used by the site template.
 * `template.integrations`: (optional) Integrations with 3rd party solutions in your template. This object is dependent on which template you're using. For @webdoc/default-template, the following integrations are available:
   * `search`: This is used as the backend for the global site search. You'll need to create an Algolia account yourself and provide
     the `apiKey`, `appId`, `indexName`. (The only supported provider is "algolia" right now)
+
+### Tutorial configuration
+
+Tutorials can be structured in a hierarchy using JSON files in the tutorials directory. If you have multiple JSON configuration, they
+are deep-merged before being processed.
+
+#### Per-tutorial configuration
+
+Tutorials are referenced using their file name - so make sure all file names in the tutorial directory are unique. To configure a specific
+tutorial file, any configuration should reference it by the file name (excluding the extension). For example, to configure "hello-world.md":
+
+```json
+{
+  "hello-world": {
+    "title": "Hello world! by webdoc"
+  }
+}
+```
+
+* `title` - This is what the navigation sidebar will list the tutorial as.
+
+#### Defining a hierarchy
+
+You can also define children in tutorial configurators inline:
+
+```json
+{
+  "hello-world": {
+    "title": "Hello world! by webdoc",
+    "children": {
+      "chapter-1": {
+        "title": "Chapter 1"
+      },
+      "chapter-2": {
+        "title": "Chapter 2"
+      }
+    }
+  },
+  "next-steps": {
+    "title": "Next-steps"
+  }
+}
+```
+
+In this configuration, "Chapter 1" and "Chapter 2" will be items under the "Hello world!" category.
+
+#### Referencing other tutorials
+
+Instead of defining tutorials inline in the `children` object, you can add them to the root and then reference
+them by name in a `children` array.
+
+```json
+{
+  "hello-world": {
+    "title": "Hello world! by webdoc",
+    "children": [
+      "chapter-1",
+      "chapter-2"
+    ]
+  },
+  "chapter-1": {
+    "title": "Chapter 1"
+  },
+  "chapter-2": {
+    "title": "Chapter 2"
+  },
+  "next-steps": {
+    "title": "Next-steps"
+  }
+}
+```
+
+The above configuration is equivalent to the one defining "Chapter 1" and "Chapter 2" children inline "Hello world!". This way,
+you can also split the configuration into multiple files:
+
+**main.json**
+
+```json
+{
+  "hello-world": {
+    "title": "Hello world! by webdoc",
+    "children": [
+      "chapter-1",
+      "chapter-2"
+    ]
+  },
+  "next-steps": {
+    "title": "Next-steps"
+  }
+}
+```
+
+**chapters.json**
+
+```json
+{
+  "chapter-1": {
+    "title": "Chapter 1"
+  },
+  "chapter-2": {
+    "title": "Chapter 2"
+  }
+}
+```

packages/webdoc-cli/src/config.js

@@ -1,5 +1,6 @@
 // @flow
-import {log, tags} from "missionlog";
+
+import {log, tag} from "missionlog";
 import fs from "fs";
 import merge from "lodash.merge";
 
@@ -102,13 +103,15 @@ export function loadConfig(file: string): ConfigSchema {
   let config;
 
   if (!fs.existsSync(file)) {
-    log.warn(tags.Config, `Configuration file not found at: ${file}`);
+    log.warn(tag.Config, `Configuration file not found at: ${file}`);
     config = defaultConfig;
   } else {
     const userConfig = JSON.parse(fs.readFileSync(file, "utf8"));
     config = merge(defaultConfig, userConfig);
   }
 
+  log.info(tag.CLI, "Loaded configuration");
+
   return config;
 }