Tutorials rendering in @webdoc/default-template working correctly!

Author: ShukantPal

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

@@ -80,10 +80,10 @@ export function loadTutorials(tutorialsDir?: string): Tutorial[] {
     // Tutorials can be part of the doc-tree!
     tutorials.push(createTutorialDoc(
       fileName,
-      relativePath
+      path.join('tutorials', relativePath
         .replace(".html", "")
         .replace(".htm", "")
-        .replace(".md", ""),
+        .replace(".md", "")),
       fileContent,
     ));
   }

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

@@ -12,7 +12,7 @@ type TutorialConfigurator = {
     "title": ?string,
     "kind"?: "category",
     "children": TutorialConfigurator[] | {
-      [id: string]: TutorialReference
+      [id: string]: TutorialConfigurator
     }
 };
 
@@ -41,7 +41,7 @@ export function morphTutorials(
   tutorials.forEach((t) => tutorialDB.set(t.name, t));
 
   // This is the new list of tutorials
-  const rootTutorials = [];
+  let rootTutorials = [];
 
   // eslint-disable-next-line guard-for-in
   for (const [name, configurator] of Object.entries(tconf)) {
@@ -59,6 +59,12 @@ export function morphTutorials(
     rootTutorials.push(tdoc);
   }
 
+  // Go through rootTutorials and filter out any ones that became nested by a tutorial
+  // after they were declared.
+  rootTutorials = rootTutorials.filter((tutorial) => !nestedTutorials.has(tutorial.name));
+
+  console.log(rootTutorials.map((t) => t.name))
+
   return rootTutorials;
 }
 
@@ -83,6 +89,7 @@ function resolveConfigurator(
       // eslint-disable-next-line no-prototype-builtins
       if (configurator.children.hasOwnProperty(name)) {
         tdoc.members.push(tutorialDoc(name, (childConf: any)));
+        resolveConfigurator(name, (childConf: any));
       }
     }
   }

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

@@ -18,16 +18,19 @@ function crawlTutorials(docTree /*: RootDoc */)/*: ?ExplorerTarget */ {
     return null;
   }
 
-  const rootTarget = {
-    title: "Tutorials",
-    page: linker.createURI("tutorials/index.html"),
+  let rootTarget = {
     children: {},
   };
 
   for (const tutorial of docTree.tutorials) {
     buildTutorialTargets(tutorial, rootTarget);
   }
 
+  // No need for single top-level item
+  if (Object.keys(rootTarget.children).length === 1) {
+    rootTarget = { children: rootTarget.children[Object.keys(rootTarget.children)[0]].children };
+  }
+
   return rootTarget;
 }
 
@@ -37,16 +40,24 @@ function buildTutorialTargets(
 )/*: ExplorerTarget */ {
   const tutorialTarget = {
     title: tutorial.title,
-    page: linker.createURI(tutorial.route),
+    page: tutorial.route ? linker.getURI(tutorial) : null,
     children: {},
   };
 
-  parent.title = tutorialTarget;
   parent.children[tutorialTarget.title] = tutorialTarget;
 
-  for (const childTutorial of tutorial.members) {
-    if (childTutorial.type === "TutorialDoc") {
-      buildTutorialTargets(childTutorial, tutorialTarget);
+  if (tutorial.members.length > 0) {
+    if (tutorialTarget.page) {
+      tutorialTarget.children.overview = {
+        title: '(overview)',
+        page: tutorialTarget.page,
+      };
+    }
+
+    for (const childTutorial of tutorial.members) {
+      if (childTutorial.type === "TutorialDoc") {
+        buildTutorialTargets(childTutorial, tutorialTarget);
+      }
     }
   }
 

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

@@ -1,3 +1,7 @@
 // @flow
 
+/*::
+ export {CrawlData} from './crawl';
+ */
+
 exports.crawl = require("./crawl").crawl;

packages/webdoc-default-template/publish.js

@@ -22,8 +22,11 @@ const {categoryFilterPlugin} = require("./helper/renderer-plugins/category-filte
 /*::
 import type {
   Doc,
-  RootDoc
+  RootDoc,
+  TutorialDoc,
 } from "@webdoc/types";
+
+import type {CrawlData} from './crawl';
 */
 
 Object.assign(linker.standaloneDocTypes, [
@@ -96,6 +99,7 @@ exports.publish = async function publish(options /*: PublishOptions */) {
   outMainPage(path.join(outDir, indexRelative), pipeline, options.config);
   outIndexes(outDir, pipeline, options.config, crawlData.index);
   outReference(outDir, pipeline, options.config, docTree);
+  outTutorials(outDir, pipeline, options.config, docTree);
 
   pipeline.close();
 };
@@ -130,6 +134,17 @@ function outExplorerData(outDir /*: string */, crawlData /*: CrawlData */) {
       (err) => {
         if (err) throw err;
       });
+
+    if (crawlData.tutorials) {
+      fse.writeFile(
+        path.join(explorerDir, "./tutorials.json"),
+        JSON.stringify(crawlData.tutorials),
+        "utf8",
+        (err) => {
+          if (err) throw err;
+        },
+      );
+    }
   });
 }
 
@@ -175,7 +190,7 @@ async function outReadme(
   }
 
   pipeline.render("pages/main-page.tmpl", {
-    docs: [],
+    document: null,
     readme,
     title: "Documentation",
     env: config,
@@ -247,7 +262,7 @@ function outReference(
       );
     } else {
       pipeline.render("document.tmpl", {
-        docs: [doc],
+        document: doc,
         title: doc.name,
         env: config,
       }, {
@@ -256,3 +271,26 @@ function outReference(
     }
   }
 }
+
+function outTutorials(
+  outDir /*: string */,
+  pipeline /*: TemplatePipeline */,
+  config /*: WebdocConfig */,
+  docTree /*: RootDoc */,
+) {
+  function out(tutorial /*: TutorialDoc */) {
+    const uri = linker.getURI(tutorial);
+
+    pipeline.render("tutorial.tmpl", {
+      document: tutorial,
+      title: tutorial.title,
+      env: config,
+    }, {
+      outputFile: path.join(outDir, uri),
+    });
+
+    tutorial.members.forEach((out /*: any */));
+  }
+
+  docTree.tutorials.forEach(out);
+}

packages/webdoc-default-template/src/app/components/Explorer/index.js

@@ -78,10 +78,10 @@ export default connect(({
   const {root} = useExplorerStyles();
   const toggleOpen = React.useCallback(() => setOpen(!isOpen), [isOpen]);
   const children = [];
-  const sitePrefix = window.appData.siteRoot ? "/" + window.appData.siteRoot + "/" : "/";
+  const explorerTree = window.appData.explorerTree;
 
   if (!fetched) {
-    fetch(sitePrefix + "explorer/reference.json")
+    fetch(explorerTree)
       .then((response) => {
         if (response.ok) {
           response.json().then((idata) => {

packages/webdoc-default-template/static/scripts/default-template.js

@@ -9488,10 +9488,10 @@ function makeIds(data, collector) {
     return setOpen(!isOpen);
   }, [isOpen]);
   var children = [];
-  var sitePrefix = window.appData.siteRoot ? "/" + window.appData.siteRoot + "/" : "/";
+  var explorerTree = window.appData.explorerTree;
 
   if (!fetched) {
-    fetch(sitePrefix + "explorer/reference.json").then(function (response) {
+    fetch(explorerTree).then(function (response) {
       if (response.ok) {
         response.json().then(function (idata) {
           var defaultExpanded = new Set();

packages/webdoc-default-template/tmpl/document.tmpl

@@ -1,12 +1,9 @@
 <?js
-/**
- * Documentation object render component.
- */
-const
-  docData = obj,
-  docList = obj.docs;
+  /**
+   * Documentation object render component.
+   */
+  const doc = obj.document;
 
-docList.forEach((doc) => {
   const titleMods = [
     doc.deprecated ? "document__title_deprecated" : ""
   ].join(" ");
@@ -98,5 +95,4 @@ docList.forEach((doc) => {
   </div>
   <footer class="footer" id="footer-mount-point"></footer>
 </div>
-<?js= this.partial("components/members-explorer/index.tmpl", doc) ?>
-<?js }); ?>
+<?js= this.partial("components/members-explorer/index.tmpl", doc) ?>

packages/webdoc-default-template/tmpl/layout.tmpl

@@ -3,6 +3,7 @@
  * Global layout render component.
  */
 const rootData = obj;
+const document = rootData.document;
 const config = rootData.env.template;
 const siteRoot = this.getPlugin("linker").siteRoot;
 const sitePrefix = siteRoot ? siteRoot + "/" : siteRoot;
@@ -26,6 +27,7 @@ const integrations = JSON.stringify(config.integrations);
     <script>
       window.appData = {
         applicationName: "<?js= config.applicationName ?>",
+        explorerTree: "<?js= siteRoot + "/explorer/" + (document && document.type === "TutorialDoc" ? "tutorials" : "reference") + ".json" ?>",
         siteRoot: "<?js= siteRoot ?>",
         integrations: JSON.parse(`<?js= integrations ?>`),
       };

packages/webdoc-default-template/tmpl/tutorial.tmpl

@@ -0,0 +1,10 @@
+<?js
+    /** Tutorial rendering component */
+    const document = obj.document;
+ ?>
+<div class="page-content">
+  <div class="document">
+    <?js /* Simplicity, at its finest! */ ?>
+    <?js= document.content ?>
+  </div>
+</div>