@webdoc/externalize DocumentedInterface

Author: ShukantPal

packages/eslint-config/index.js

@@ -12,7 +12,24 @@ module.exports = {
   globals: {
     Atomics: "readonly",
     SharedArrayBuffer: "readonly",
+    $Keys: "readonly",
+    $Values: "readonly",
+    $ReadOnly: "readonly",
+    $Exact: "readonly",
+    $Diff: "readonly",
+    $Rest: "readonly",
+    $PropertyType: "readonly",
+    $ElementType: "readonly",
+    $NonMaybeType: "readonly",
+    $ObjMap: "readonly",
+    $ObjMapi: "readonly",
+    $TupleMap: "readonly",
+    $Call: "readonly",
+    Class: "readonly",
     $Shape: "readonly",
+    $Exports: "readonly",
+    $Supertype: "readonly",
+    $Subtype: "readonly",
     $ReadOnlyArray: "readonly",
   },
   parser: "babel-eslint",

packages/webdoc-cli/src/index.js

@@ -126,7 +126,7 @@ async function main(argv: yargs.Argv) {
   const db = exportTaffy(documentTree);
 
   const _path = `${getTemplate(config)}/publish`;
-  // $FlowFixMe
+  // $FlowFixMe[unsupported-syntax]
   const template = require(_path);
 
   log.info(tag.CLI, "Executing template");

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

@@ -2,7 +2,7 @@
 
 const {crawlReference} = require("./crawl-reference-explorer");
 const {crawlTutorials} = require("./crawl-tutorials");
-const {traverse} = require("@webdoc/model");
+const model = require("@webdoc/model");
 const {linker} = require("../linker");
 
 // This file crawls the document tree to:
@@ -15,6 +15,10 @@ import type {
   DocType,
 } from "@webdoc/types";
 
+import type {
+  LinkTable,
+} from "@webdoc/template-library";
+
 import type {ExplorerTarget} from './crawl-reference-explorer';
 
 export type CategorizedDocumentList = {
@@ -63,18 +67,22 @@ function crawl(tree /*: RootDoc */, index /*: string */)/*: CrawlData */ {
 
 module.exports = ({crawl}/*: {crawl: typeof crawl} */);
 
-function buildLinks(tree /*: RootDoc */) /*: void */ {
-  traverse(tree, (doc) => {
+function buildLinks(tree /*: RootDoc */) /*: LinkTable */ {
+  const linkTable = {};
+
+  model.traverse(tree, (doc) => {
     if (doc.type === "RootDoc") {
       doc.packages.forEach((packageDoc) => {
-        linker.getURI(packageDoc);
+        linkTable[packageDoc.path] = linker.getURI(packageDoc);
       });
 
       return;
     }
 
-    linker.getURI(doc);
+    linkTable[doc.path] = linker.getURI(doc);
   });
+
+  return linkTable;
 }
 
 function buildIndex(
@@ -86,7 +94,7 @@ function buildIndex(
     classes: Object.assign(([] /*: any */), {url: classIndexUrl}),
   };
 
-  traverse(tree, (doc) => {
+  model.traverse(tree, (doc) => {
     switch (doc.type) {
     case "ClassDoc":
       index.classes.push(doc);

packages/webdoc-default-template/publish.js

@@ -89,7 +89,10 @@ exports.publish = async function publish(options /*: PublishOptions */) {
           crawlData.tutorials.children[Object.keys(crawlData.tutorials.children)[0]].page,
       },
     }),
-  });
+  }, _.pick(config.template.appBar.items, [
+    "reference",
+    "tutorials",
+  ]));
   const renderer = new TemplateRenderer(path.join(__dirname, "tmpl"), null, docTree)
     .setLayoutTemplate("layout.tmpl")
     .installPlugin("linker", linker)

packages/webdoc-externalize/index.js.flow

@@ -1,11 +1,27 @@
 declare module "@webdoc/externalize" {
   import type {RootDoc} from "@webdoc/types";
 
-  declare export function readDoctree(data: string): RootDoc;
-  declare export function writeDoctree(doc: RootDoc): string;
+  declare export type DocumentedInterface = {
+    version: string;
+    metadata: {
+      linker?: "require('@webdoc/template-library').LinkerPlugin" | string;
+      [string]: string;
+    };
+    root: RootDoc;
+    registry: {
+      [string]: {
+        uri: string;
+      };
+    };
+  };
+
+  declare export function fromTree(tree: RootDoc): DocumentedInterface;
+  declare export function read(data: string): DocumentedInterface;
+  declare export function write(doc: DocumentedInterface): string;
 
   declare export default {
-    readDoctree: readDoctree,
-    writeDoctree: writeDoctree
+    fromTree,
+    read,
+    write,
   };
 }

packages/webdoc-externalize/package.json

@@ -15,7 +15,7 @@
   "main": "index.js",
   "directories": {
     "lib": "lib",
-    "test": "__tests__"
+    "unit-test": "mocha ./test/* --require ../../scripts/configureWebdocTesting"
   },
   "files": [
     "lib"
@@ -40,7 +40,8 @@
   "dependencies": {
     "@babel/core": "^7.9.0",
     "@webdoc/model": "^1.3.2",
-    "@webdoc/types": "^1.3.2"
+    "@webdoc/types": "^1.3.2",
+    "lodash": "^4.17.20"
   },
   "devDependencies": {
     "@babel/core": "^7.9.0",
@@ -52,6 +53,7 @@
     "@babel/register": "^7.9.0",
     "@webdoc/babel-preset": "^1.0.0",
     "@webdoc/eslint-config": "^1.0.0",
+    "@webdoc/parser": "^1.3.2",
     "del": "5.1.0",
     "eslint": "^6.8.0",
     "flow-bin": "^0.130.0",

packages/webdoc-externalize/src/SanitizedDoc.js

@@ -0,0 +1,39 @@
+import type {BaseDoc, Param} from "@webdoc/types";
+
+// NOTE: "description" is truncated so it should not be in these lists.
+
+// Props that are copied from all documents, without any restrictions.
+export const BASE_PROPS: Array<$Keys<BaseDoc>> = [
+  "id",
+  "name",
+  "brief",
+  "abstract",
+  "access",
+  "authors",
+  "copyright",
+  "defaultValue",
+  "deprecated",
+  "examples",
+  "license",
+  "readonly",
+  "scope",
+  "see",
+  "since",
+  "type",
+  "version",
+];
+
+// Props that hold document links
+export const LINK_PROPS = [
+  "extends",
+  "implements",
+  "mixes",
+];
+
+// Props from params to be copied without serialization
+export const PARAM_PROPS: Array<$Keys<Param>> = [
+  "identifier",
+  "optional",
+  "default",
+  "variadic",
+];

packages/webdoc-externalize/src/const.js

@@ -1,9 +1,18 @@
-import readDoctree from "./readDoctree";
-import writeDoctree from "./writeDoctree";
+import write, {fromTree} from "./write";
+import read from "./read";
 
 export default {
-  readDoctree,
-  writeDoctree,
+  fromTree,
+  readDoctree: read,
+  read,
+  writeDoctree: write,
+  write,
 };
 
-export {readDoctree, writeDoctree};
+export {
+  fromTree,
+  read,
+  read as readDoctree,
+  write,
+  write as writeDoctree,
+};

packages/webdoc-externalize/src/index.js

@@ -0,0 +1,39 @@
+// @flow
+
+import type {RootDoc} from "@webdoc/types";
+
+export type SerializedDataType = {
+  tokens: Array<{
+    value: string,
+    kind: "link" | "canonical",
+  }>,
+  template: string,
+};
+
+export type SerializedParam = {
+  identifier: string,
+  dataType?: ?SerializedDataType,
+  description: string,
+  optional?: string,
+  default?: string,
+  variadic?: boolean,
+};
+
+export type SerializedReturn = {
+  description: string,
+  dataType: SerializedDataType,
+};
+
+export type DocumentedInterface = {
+  version: string;
+  metadata: {
+    linker?: "require('@webdoc/template-library').LinkerPlugin" | string;
+    [string]: string;
+  };
+  root: RootDoc;
+  registry: {
+    [string]: {
+      uri: string;
+    };
+  };
+};