Add support for .webdocignore and "category" tutorials

Author: ShukantPal

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/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;
 }
 

packages/webdoc-cli/src/index.js

@@ -63,6 +63,7 @@ async function main(argv: yargs.Argv) {
   const config = loadConfig(argv.config);
   const tutorials = loadTutorials(argv.tutorials);
 
+
   if (argv.siteRoot) {
     config.template.siteRoot = argv.siteRoot;
   }
@@ -105,7 +106,8 @@ async function main(argv: yargs.Argv) {
   }
 
   try {
-    parse(sourceFiles, documentTree);
+    if (!argv.skipAPI)
+      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

@@ -3,6 +3,7 @@
 import type {Tutorial} from "@webdoc/types";
 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";
@@ -20,23 +21,51 @@ export function loadTutorials(tutorialsDir?: string): Tutorial[] {
     return [];
   }
 
+  if (!path.isAbsolute(tutorialsDir)) {
+    tutorialsDir = path.join(process.cwd(), tutorialsDir);
+  }
+
   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')
+      .map((line) => line.trim())
+      .filter((line) => !line.startsWith('#'))
+    : [];
+
+  if (webdocIgnoreExists) {
+    log.info(tag.CLI, "Found .webdocignore in the tutorials directory");
+  }
+
   let tutorialConf = null;
   let tutorials: Tutorial[] = [];
 
   for (let i = 0; i < tutorialFiles.length; i++) {
     let fileName = tutorialFiles[i];
 
+    const relativePath = path.relative(tutorialsDir, fileName);
+
+    // Really simple check to ignore files using .webdocignore (undocumented feature)
+    if (webdocIgnorePatterns.some(
+      (pattern) => relativePath.startsWith(pattern)
+    )) {
+      continue;
+    }
+
     if (fileName.endsWith(".json")) {
       const fileJSON = JSON.parse(fs.readFileSync(fileName, "utf8"));
 
       tutorialConf = merge(tutorialConf || {}, fileJSON);
+      log.info(tag.CLI, "Found tutorial configuration: " + relativePath);
+
       continue;
     }
 
     if (!fileName.endsWith(".html") && !fileName.endsWith(".htm") && !fileName.endsWith(".md")) {
       continue;
     }
+    log.info(tag.CLI, "Found tutorial " + relativePath);
 
     let fileContent = fs.readFileSync(fileName, "utf8");
 

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

@@ -1,6 +1,7 @@
 // @flow
 
 import type {TutorialDoc} from "@webdoc/types";
+import {createTutorialDoc} from "@webdoc/model";
 
 // This file morphs the tutorials hiearchy to that specified by the tutorial JSON configurations
 // provided by the user.
@@ -9,6 +10,7 @@ type TutorialReference = string;
 
 type TutorialConfigurator = {
     "title": ?string,
+    "kind"?: "category",
     "children": TutorialConfigurator[] | {
       [id: string]: TutorialReference
     }
@@ -90,14 +92,15 @@ function resolveConfigurator(
 
 // Fetch the tutorial-doc based off its name.
 function tutorialDoc(name: string, configurator?: TutorialConfigurator): TutorialDoc {
-  if (!tutorialDB.has(name)) {
+  let tdoc = tutorialDB.get(name);
+
+  if (!tdoc && configurator?.kind !== "category") {
     throw new Error("There is no such tutorial '" + name + "'");
   }
-
-  const tdoc = tutorialDB.get(name);
-
   if (!tdoc) {
-    throw new Error("NOT FOUND");
+    // category tutorial
+    tdoc = createTutorialDoc(name, '');
+    tutorialDB.set(name, tdoc);
   }
   if (configurator) {
     tdoc.title = configurator.title || name;

packages/webdoc-model/src/doc.js

@@ -7,6 +7,7 @@ import type {
   DocType,
   PackageDoc,
   RootDoc,
+  TutorialDoc,
 } from "@webdoc/types";
 import {nanoid} from "nanoid";
 
@@ -129,6 +130,31 @@ export function createPackageDoc(
   };
 }
 
+/**
+ * Creates a {@link TutorialDoc}.
+ *
+ * @param title - The title of the tutorial.
+ * @param content - The text-encoded content of the tutorial.
+ * @param data - Additional data about the tutorial.
+ */
+export function createTutorialDoc(
+  title: string,
+  content: string,
+  data?: $Shape<TutorialDoc>,
+): TutorialDoc {
+  return {
+    id: `tutorial-${title}`,
+    title,
+    content,
+    name: title,
+    path: title,
+    stack: [title],
+    members: [],
+    type: "TutorialDoc",
+    ...data,
+  }
+}
+
 /**
  * Searches for the doc named {@code lname} in the given scoped documentation.
  *