documentary - npm Package Compare versions

Comparing version 1.1.0 to 1.2.0

build/bin/run.js

@@ -8,8 +8,6 @@ "use strict";
 
-var _Toc = _interopRequireDefault(require("../lib/Toc"));
+var _Toc = require("../lib/Toc");
 
 var _util = require("util");
 
-var _catchment = _interopRequireDefault(require("catchment"));
-
 var _fs = require("fs");
@@ -35,15 +33,2 @@
 };
-
-const getToc = async path => {
-  const md = (0, _fs.createReadStream)(path);
-  const rs = new _Toc.default();
-  md.pipe(rs);
-  const {
-    promise
-  } = new _catchment.default({
-    rs
-  });
-  const t = await promise;
-  return t.trim();
-};
 /**
@@ -59,3 +44,3 @@ * @param {string} path
   LOG('reading %s', path);
-  const t = await getToc(path);
+  const t = await (0, _Toc.getToc)(path);
 
@@ -62,0 +47,0 @@ if (toc) {

build/lib/index.js

@@ -6,7 +6,8 @@ "use strict";
 });
-exports.getLink = void 0;
+exports.titleRule = exports.methodTitleRe = exports.titleReplacer = exports.replaceTitle = exports.tableRule = exports.getLink = void 0;
 
-// koa2jsxreducer-functionview-containeractions-objectstatic-boolean--truerender-function-function
-// koa2jsxbrnbspnbspreducer-functionbrnbspnbspview-containerbrnbspnbspactions-objectbrnbspnbspstatic-boolean--truebrnbspnbsprender-functionbr-function
-//        brnbspnbsp                brnbspnbsp              brnbspnbsp              brnbspnbsp                    brnbspnbsp               br
+var _util = require("util");
+
+const LOG = (0, _util.debuglog)('doc');
+
 const getLink = title => {
@@ -18,2 +19,80 @@ const l = title.replace(/<br\/>/g, '').replace(/&nbsp;/g, '').replace(/[^\w-\d ]/g, '').toLowerCase().replace(/[, ]/g, '-');
 exports.getLink = getLink;
+
+const tableRule = (match, table) => {
+  const t = table.trim();
+
+  try {
+    const res = JSON.parse(t);
+    const [header, ...rows] = res;
+    const a = [getRow(header), getRow(header.map(({
+      length
+    }) => '-'.repeat(length))), ...rows.map(getRow)];
+    return a.join('\n');
+  } catch (err) {
+    LOG('could not parse the table');
+    return match;
+  }
+};
+
+exports.tableRule = tableRule;
+
+const getRow = row => {
+  const s = `| ${row.join(' | ')} |`;
+  return s;
+};
+
+const replaceTitle = (level, isAsync, method, returnType, title) => {
+  const t = title.trim();
+  const sig = `${level} ${isAsync ? '`async ' : '`'}${method}(`;
+  const endSig = `): ${returnType ? returnType : 'void'}\``;
+  const nl = '<br/>'; // '<br/>'
+
+  const i = '&nbsp;&nbsp;'; // '&nbsp;
+
+  const single = `${sig}${endSig}`;
+  if (!t.trim()) return single;
+  /** @type {[]} */
+
+  const args = JSON.parse(t);
+  if (!args.length) return single;
+  const lines = args.map(([name, type]) => {
+    if (typeof type == 'string') {
+      return `\`${name}: ${type},\``;
+    }
+
+    const l = Object.keys(type).map(key => {
+      // const isRequired = key.endsWith('?')
+      const [propType, defaultValue] = type[key]; // static?: boolean = true,
+
+      return `${key}: ${propType}${defaultValue ? ` = ${defaultValue}` : ''}`;
+    }).map(line => `\`${line},\``).join(`${nl}${i.repeat(2)}`);
+    const n = `\`${name}: {\`${nl}${i.repeat(2)}${l}${nl}${i.repeat(1)}\`},\``;
+    return n;
+  });
+  const nls = `${nl}${i.repeat(1)}`;
+  const s = lines.join(nls);
+  const res = `${sig}\`${nls}${s}${nl}\`${endSig}`;
+  return res;
+};
+
+exports.replaceTitle = replaceTitle;
+
+const titleReplacer = (match, level, isAsync, method, returnType, title) => {
+  try {
+    const res = replaceTitle(level, isAsync, method, returnType, title);
+    return res;
+  } catch (err) {
+    LOG('could not parse the method title');
+    return match;
+  }
+};
+
+exports.titleReplacer = titleReplacer;
+const methodTitleRe = /```(#+)( async)? (\w+)(?: => (.+)\n)?([\s\S]*?)```/g;
+exports.methodTitleRe = methodTitleRe;
+const titleRule = {
+  re: methodTitleRe,
+  replacement: titleReplacer
+};
+exports.titleRule = titleRule;
 //# sourceMappingURL=index.js.map

build/lib/replace-stream.js

@@ -12,13 +12,8 @@ "use strict";
 
+var _ = require(".");
+
 const LOG = (0, _util.debuglog)('doc');
-/**
- *
- * @param {string} [toc] The table of contents.
- */
 
-function createReplaceStream(toc = '') {
+function createReplaceStream(toc) {
   const s = (0, _restream.replaceStream)([{
-    re: /^%TOC%$/gm,
-    replacement: toc
-  }, {
     re: /<!--[\s\S]*?-->\n*/g,
@@ -32,28 +27,10 @@
   }, {
+    re: /^%TOC%$/gm,
+    replacement: toc
+  }, {
     re: /```table([\s\S]+?)```/g,
-
-    replacement(match, table) {
-      const t = table.trim();
-
-      try {
-        const res = JSON.parse(t);
-        const [header, ...rows] = res;
-        const a = [getRow(header), getRow(header.map(({
-          length
-        }) => '-'.repeat(length))), ...rows.map(getRow)];
-        return a.join('\n');
-      } catch (err) {
-        LOG('could not parse the table');
-        return match;
-      }
-    }
-
-  }]);
+    replacement: _.tableRule
+  }, _.titleRule]);
   return s;
 }
-
-const getRow = row => {
-  const s = `| ${row.join(' | ')} |`;
-  return s;
-};
 //# sourceMappingURL=replace-stream.js.map

build/lib/Toc.js

@@ -6,9 +6,15 @@ "use strict";
 });
-exports.default = void 0;
+exports.getToc = exports.default = void 0;
 
+var _stream = require("stream");
+
+var _catchment = _interopRequireDefault(require("catchment"));
+
+var _fs = require("fs");
+
 var _ = require(".");
 
-var _stream = require("stream");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-const re = /^ *(#+) *((?:(?!\n)[\s\S])+)\n/gm;
+const re = /(?:^|\n) *(#+) *((?:(?!\n)[\s\S])+)\n/;
 
@@ -31,17 +37,47 @@ class Toc extends _stream.Transform {
     let res;
+    const rre = new RegExp(`(?:${re.source})|(?:${_.methodTitleRe.source})`, 'g');
 
-    while ((res = re.exec(buffer)) !== null) {
-      const [, {
-        length: level
-      }, title] = res;
-      if (this.skipLevelOne && level == 1) continue;
-      const link = (0, _.getLink)(title);
-      const t = `[${title}](#${link})`;
+    while ((res = rre.exec(buffer)) !== null) {
+      let t;
+      let level;
+      let link;
+
+      if (res[1]) {
+        // normal title regex
+        const [, {
+          length
+        }, title] = res;
+        level = length;
+        if (this.skipLevelOne && level == 1) continue;
+        t = title;
+        link = (0, _.getLink)(title);
+      } else {
+        // the method title regex
+        try {
+          const l = res[3];
+          level = l.length;
+          const b = res.slice(4, 6).filter(a => a).join(' ').trim();
+          const json = res[7] || '[]';
+          const args = JSON.parse(json);
+          const s = args.map(([name, type]) => {
+            if (typeof type == 'string') return `${name}: ${type}`;
+            return `${name}: object`;
+          });
+          const fullTitle = (0, _.replaceTitle)(...res.slice(3)).replace(/^#+ +/, '');
+          link = (0, _.getLink)(fullTitle);
+          t = `\`${b}(${s.join(', ')})${res[6] ? `: ${res[6]}` : ''}\``;
+        } catch (err) {
+          // ok
+          continue;
+        }
+      }
+
+      const heading = `[${t}](#${link})`;
       let s;
 
       if (level == 2) {
-        s = `- ${t}`;
+        s = `- ${heading}`;
       } else {
         const p = '  '.repeat(level - 2);
-        s = `${p}* ${t}`;
+        s = `${p}* ${heading}`;
       }
@@ -53,2 +89,3 @@
 
+    re.lastIndex = -1;
     next();
@@ -58,2 +95,17 @@ }
 }
+
+exports.default = Toc;
+
+const getToc = async path => {
+  const md = (0, _fs.createReadStream)(path);
+  const rs = new Toc();
+  md.pipe(rs);
+  const {
+    promise
+  } = new _catchment.default({
+    rs
+  });
+  const t = await promise;
+  return t.trim();
+};
 /**
@@ -65,3 +117,3 @@ * @typedef {Object} Config
 
-exports.default = Toc;
+exports.getToc = getToc;
 //# sourceMappingURL=Toc.js.map

CHANGELOG.md

 ## 15 June 2018
 
+### 1.2.0
+
+- [feature] method titles generation with shorthand TOC for them.
+
 ### 1.1.0
@@ -4,0 +8,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A library to manage documentation, such as README, usage, man pages and changelog.",
@@ -15,7 +15,8 @@ "main": "build",
     "dev": "NODE_DEBUG=doc node src/bin/register",
-    "doc": "NODE_DEBUG=doc node build/bin README-source.md -o README.md",
+    "doc": "yarn dev README-source.md -o README.md",
     "start": "node build/bin",
     "example/": "yarn e example/example.js",
     "example/toc.js": "NODE_DEBUG=doc yarn e example/toc.js",
-    "build": "babel src --out-dir build --source-maps --ignore src/bin/register.js"
+    "build-src": "babel src --out-dir build --source-maps --ignore src/bin/register.js",
+    "build": "yarn-s build-src doc"
   },
@@ -22,0 +23,0 @@ "bin": {

README-source.md

@@ -99,2 +99,62 @@ # documentary
 
+### Method Title
+
+It is possible to generate neat titles useful for API documentation with `documentary`. The method signature should be specified as a `JSON` array, where every member is an argument specified as an array. The first item in the argument array is the argument name, and the second one is type. Type can be either a string, or an object. If it is an object, each value in the object will first contain the property type, and the second one the default value. To mark a property as optional, the `?` symbol can be used at the end.
+
+```#### async runSoftware => string
+[
+  ["path", "string"],
+  ["config", {
+    "View": ["Container"],
+    "actions": ["object"],
+    "static?": ["boolean", true],
+    "render?": ["function"]
+  }]
+]
+```
+
+Generated from
+
+````m
+```#️⃣#️⃣#️⃣#️⃣ async runSoftware => string
+[
+  ["path", "string"],
+  ["config", {
+    "View": ["Container"],
+    "actions": ["object"],
+    "static?": ["boolean", true],
+    "render?": ["function"]
+  }]
+]
+```
+````
+
+```#### async runSoftware
+[
+  ["path", "string"]
+]
+```
+
+Generated from
+
+````m
+```#️⃣#️⃣#️⃣#️⃣ async runSoftware => string
+[
+  ["path", "string"]
+]
+```
+````
+
+```#### runSoftware => string
+```
+
+Generated from
+
+````m
+```#️⃣#️⃣#️⃣#️⃣ async runSoftware => string
+```
+````
+
+<!-- `koa2Jsx({`<br/>&nbsp;&nbsp;`reducer: function,`<br/>&nbsp;&nbsp;`View: Container,`<br/>&nbsp;&nbsp;`actions: object,`<br/>&nbsp;&nbsp;`static?: boolean = true,`<br/>&nbsp;&nbsp;`render?: function,`<br/>`}): function` -->
+
 <!-- It will also include valid URLs used on GitHub to skip to the title when complex titles are given.
@@ -174,3 +234,3 @@
 
-`koa2Jsx({`<br/>&nbsp;&nbsp;`reducer: function,`<br/>&nbsp;&nbsp;`View: Container,`<br/>&nbsp;&nbsp;`actions: object,`<br/>&nbsp;&nbsp;`static?: boolean = true,`<br/>&nbsp;&nbsp;`render?: function,`<br/>`}): function` -->
+-->
 
@@ -177,0 +237,0 @@ ### `new Toc()`

README.md

@@ -20,2 +20,6 @@ # documentary
   * [Tables Display](#tables-display)
+  * [Method Title](#method-title)
+    * [`async runSoftware(path: string, config: object): string`](#async-runsoftwarepath-stringconfig-view-containeractions-objectstatic-boolean--truerender-function-string)
+    * [`async runSoftware(path: string)`](#async-runsoftwarepath-string-void)
+    * [`runSoftware(): string`](#runsoftware-string)
 - [CLI](#cli)
@@ -103,2 +107,45 @@ - [API](#api)
 
+### Method Title
+
+It is possible to generate neat titles useful for API documentation with `documentary`. The method signature should be specified as a `JSON` array, where every member is an argument specified as an array. The first item in the argument array is the argument name, and the second one is type. Type can be either a string, or an object. If it is an object, each value in the object will first contain the property type, and the second one the default value. To mark a property as optional, the `?` symbol can be used at the end.
+
+#### `async runSoftware(`<br/>&nbsp;&nbsp;`path: string,`<br/>&nbsp;&nbsp;`config: {`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`View: Container,`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`actions: object,`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`static?: boolean = true,`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`render?: function,`<br/>&nbsp;&nbsp;`},`<br/>`): string`
+
+Generated from
+
+````m
+```#️⃣#️⃣#️⃣#️⃣ async runSoftware => string
+[
+  ["path", "string"],
+  ["config", {
+    "View": ["Container"],
+    "actions": ["object"],
+    "static?": ["boolean", true],
+    "render?": ["function"]
+  }]
+]
+```
+````
+
+#### `async runSoftware(`<br/>&nbsp;&nbsp;`path: string,`<br/>`): void`
+
+Generated from
+
+````m
+```#️⃣#️⃣#️⃣#️⃣ async runSoftware => string
+[
+  ["path", "string"]
+]
+```
+````
+
+#### `runSoftware(): string`
+
+Generated from
+
+````m
+```#️⃣#️⃣#️⃣#️⃣ async runSoftware => string
+```
+````
+
 ## CLI
@@ -105,0 +152,0 @@

No alert changes

Improved metrics

Total package byte prevSize

45858

increased by33.14%

Lines of code

357

increased by27.05%

Number of lines in readme file

227

increased by26.11%

Worsened metrics

Number of low supply chain risk alerts

5

increased by25%

No dependency changes