Crawl 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"

packages/webdoc-cli/src/index.js

@@ -100,14 +100,14 @@ async function main(argv: yargs.Argv) {
   const sourceFiles = sources(config, documentTree);
 
   documentTree.children = documentTree.members;
+  documentTree.tutorials.push(...tutorials);
 
   if (config.opts && config.opts.export) {
     fse.ensureFileSync(config.opts.export);
   }
 
   try {
-    if (!argv.skipAPI)
-      parse(sourceFiles, documentTree);
+    parse(sourceFiles, documentTree);
   } catch (e) {
     // Make sure we get that API structure out so the user can debug the problem!
     if (config.opts && config.opts.export) {

packages/webdoc-cli/src/load-tutorials/load-tutorials.js

@@ -1,9 +1,10 @@
 // @flow
 
+import {log, tag} from "missionlog";
 import type {Tutorial} from "@webdoc/types";
+import {createTutorialDoc} from "@webdoc/model";
 import fs from "fs";
 import globby from "globby";
-import {log, tag} from "missionlog";
 import merge from "lodash.merge";
 import {morphTutorials} from "./morph-tutorials";
 import path from "path";
@@ -27,12 +28,12 @@ export function loadTutorials(tutorialsDir?: string): Tutorial[] {
 
   const tutorialFiles = globby.sync(path.join(tutorialsDir, "./**/*"));
   const webdocIgnoreExists = fs.existsSync(path.join(tutorialsDir, "./.webdocignore"));
-  const webdocIgnorePatterns: $ReadOnlyArray<string> = webdocIgnoreExists
-    ? fs.readFileSync(path.join(tutorialsDir, ".webdocignore"), 'utf8')
-      .split('\n')
+  const webdocIgnorePatterns: $ReadOnlyArray<string> = webdocIgnoreExists ?
+    fs.readFileSync(path.join(tutorialsDir, ".webdocignore"), "utf8")
+      .split("\n")
       .map((line) => line.trim())
-      .filter((line) => !line.startsWith('#'))
-    : [];
+      .filter((line) => !line.startsWith("#")) :
+    [];
 
   if (webdocIgnoreExists) {
     log.info(tag.CLI, "Found .webdocignore in the tutorials directory");
@@ -48,7 +49,7 @@ export function loadTutorials(tutorialsDir?: string): Tutorial[] {
 
     // Really simple check to ignore files using .webdocignore (undocumented feature)
     if (webdocIgnorePatterns.some(
-      (pattern) => relativePath.startsWith(pattern)
+      (pattern) => relativePath.startsWith(pattern),
     )) {
       continue;
     }
@@ -77,16 +78,14 @@ export function loadTutorials(tutorialsDir?: string): Tutorial[] {
     fileName = fileName.slice(0, fileName.lastIndexOf("."));
 
     // Tutorials can be part of the doc-tree!
-    tutorials.push({
-      id: `tutorial-${fileName}`,
-      name: fileName,
-      path: fileName,
-      stack: [fileName],
-      title: fileName,
-      content: fileContent,
-      members: [],
-      type: "TutorialDoc",
-    });
+    tutorials.push(createTutorialDoc(
+      fileName,
+      relativePath
+        .replace(".html", "")
+        .replace(".htm", "")
+        .replace(".md", ""),
+      fileContent,
+    ));
   }
 
   if (tutorialConf) {

packages/webdoc-cli/src/load-tutorials/morph-tutorials.js

@@ -94,12 +94,12 @@ function resolveConfigurator(
 function tutorialDoc(name: string, configurator?: TutorialConfigurator): TutorialDoc {
   let tdoc = tutorialDB.get(name);
 
-  if (!tdoc && configurator?.kind !== "category") {
+  if (!tdoc && (!configurator || configurator.kind !== "category")) {
     throw new Error("There is no such tutorial '" + name + "'");
   }
   if (!tdoc) {
     // category tutorial
-    tdoc = createTutorialDoc(name, '');
+    tdoc = createTutorialDoc(name, "", "");
     tutorialDB.set(name, tdoc);
   }
   if (configurator) {

packages/webdoc-default-template/helper/crawl/crawl-reference-explorer.js

@@ -155,6 +155,16 @@ function traversePackage(doc /*: Doc | PackageDoc */, context /*: Object */, par
   context.exit(doc);
 }
 
+/*::
+export type ExplorerTarget = {
+  title: string,
+  page?: ?string,
+  children: {
+    [id: string]: ExplorerTarget,
+  }
+};
+ */
+
 function buildExplorerTargetsTree(
   node /*: ExplorerNode */,
   parentTitle /*: string */ = "",

packages/webdoc-default-template/helper/crawl/crawl-tutorials.js

@@ -0,0 +1,56 @@
+// @flow
+
+const {linker} = require("../linker");
+
+/*::
+ import type {
+   Doc,
+   RootDoc,
+   TutorialDoc,
+ } from "@webdoc/types";
+
+ import type { ExplorerTarget } from './crawl-reference-explorer';
+ */
+
+// Build a explorer tree for tutorials
+function crawlTutorials(docTree /*: RootDoc */)/*: ?ExplorerTarget */ {
+  if (!docTree.tutorials.length) {
+    return null;
+  }
+
+  const rootTarget = {
+    title: "Tutorials",
+    page: linker.createURI("tutorials/index.html"),
+    children: {},
+  };
+
+  for (const tutorial of docTree.tutorials) {
+    buildTutorialTargets(tutorial, rootTarget);
+  }
+
+  return rootTarget;
+}
+
+function buildTutorialTargets(
+  tutorial /*: TutorialDoc */,
+  parent /*: ExplorerTarget */,
+)/*: ExplorerTarget */ {
+  const tutorialTarget = {
+    title: tutorial.title,
+    page: linker.createURI(tutorial.route),
+    children: {},
+  };
+
+  parent.title = tutorialTarget;
+  parent.children[tutorialTarget.title] = tutorialTarget;
+
+  for (const childTutorial of tutorial.members) {
+    if (childTutorial.type === "TutorialDoc") {
+      buildTutorialTargets(childTutorial, tutorialTarget);
+    }
+  }
+
+  return tutorialTarget;
+}
+
+exports.crawlTutorials = crawlTutorials;