documentary - npm Package Compare versions

Comparing version 1.5.0 to 1.6.0

build/bin/index.js

@@ -73,5 +73,15 @@ #!/usr/bin/env node
 
+  let debounce = false;
+
   if (_watch) {
-    (0, _fs.watch)(_source, async () => {
-      await doc(_source, _output, _toc);
+    (0, _fs.watch)(_source, {
+      recursive: true
+    }, async () => {
+      if (!debounce) {
+        debounce = true;
+        await doc(_source, _output, _toc);
+        setTimeout(() => {
+          debounce = false;
+        }, 100);
+      }
     });
@@ -78,0 +88,0 @@ }

build/lib/replace-stream.js

@@ -10,77 +10,74 @@ "use strict";
 
-var _util = require("util");
-
 var _rules = require("./rules");
 
-var _lib = require("../lib");
+var _table = _interopRequireWildcard(require("./rules/table"));
 
-var _table = _interopRequireDefault(require("./rules/table"));
+var _methodTitle = _interopRequireWildcard(require("./rules/method-title"));
 
-var _methodTitle = _interopRequireDefault(require("./rules/method-title"));
+var _tree = _interopRequireDefault(require("./rules/tree"));
 
 var _example = _interopRequireDefault(require("./rules/example"));
 
-var _spawncommand = _interopRequireDefault(require("spawncommand"));
+var _markers = require("./markers");
 
+var _fork = _interopRequireDefault(require("./rules/fork"));
+
+var _ = require(".");
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-const LOG = (0, _util.debuglog)('doc');
+function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { var desc = Object.defineProperty && Object.getOwnPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : {}; if (desc.get || desc.set) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } } newObj.default = obj; return newObj; } }
 
 function createReplaceStream(toc) {
   const tocRule = (0, _rules.createTocRule)(toc);
-  const codeBlocks = [];
-  const marker = `%%_DOCUMENTARY_REPLACEMENT_${Date.now()}_%%`;
-  const s = new _restream.Replaceable([_rules.commentRule, {
-    re: new RegExp(_rules.codeRe, 'g'),
+  const {
+    table,
+    methodTitle,
+    code,
+    innerCode,
+    linkTitle
+  } = (0, _markers.makeMarkers)({
+    table: _table.tableRe,
+    methodTitle: _methodTitle.methodTitleRe,
+    code: _rules.codeRe,
+    innerCode: _rules.innerCodeRe,
+    linkTitle: _rules.linkTitleRe
+  });
+  const [cutCode, cutTable, cutMethodTitle, cutInnerCode] = [code, table, methodTitle, innerCode, linkTitle].map(marker => {
+    const rule = (0, _markers.makeInitialRule)(marker);
+    return rule;
+  });
+  const [insertCode, insertTable, insertMethodTitle, insertInnerCode] = [code, table, methodTitle, innerCode, linkTitle].map(marker => {
+    const rule = (0, _markers.makeRule)(marker);
+    return rule;
+  });
+  const s = new _restream.Replaceable([cutInnerCode, cutTable, cutMethodTitle, cutCode, _rules.commentRule, _rules.badgeRule, _tree.default, _example.default, _fork.default, tocRule, insertTable, _table.default, {
+    re: _rules.linkTitleRe,
 
-    replacement(match) {
-      if (_lib.exactTable.test(match) || _lib.exactMethodTitle.test(match)) {
-        return match;
-      }
+    replacement(match, title) {
+      const ic = new RegExp(innerCode.regExp.source).exec(title); // test please
 
-      codeBlocks.push(match);
-      return marker;
-    }
+      let link;
 
-  }, {
-    re: /%TREE (.+)%/mg,
-
-    async replacement(match, m) {
-      const args = m.split(' ');
-      const p = (0, _spawncommand.default)('tree', ['--noreport', ...args]);
-
-      try {
-        const {
-          stdout
-        } = await p.promise;
-
-        if (/\[error opening dir\]/.test(stdout)) {
-          LOG('Could not generate a tree for %s', args.join(' '));
-          return match;
-        }
-
-        return escape(stdout);
-      } catch (err) {
-        if (err.code == 'ENOENT') {
-          console.warn('tree is not installed');
-          return match;
-        }
-
-        LOG(err.message);
-        return match;
+      if (!ic) {
+        link = (0, _.getLink)(title);
+      } else {
+        const [, i] = ic;
+        const val = innerCode.map[i];
+        link = (0, _.getLink)(val);
       }
-    }
 
-  }, tocRule, _rules.badgeRule, _table.default, _methodTitle.default, _example.default, {
-    re: new RegExp(marker, 'g'),
-
-    replacement() {
-      return codeBlocks.shift();
+      return `<a name="${link}">${title}</a>`;
     }
 
-  }]);
+  }, insertMethodTitle, _methodTitle.default, insertCode, insertInnerCode, // those found inside of code blocks
+  insertTable, insertMethodTitle]);
   return s;
-}
-
-const escape = m => `\`\`\`m\n${m.trim()}\n\`\`\``;
+} // {
+//   re: /[\s\S]*/,
+//   replacement(match) {
+//     debugger
+//     return match
+//   },
+// },
 //# sourceMappingURL=replace-stream.js.map

build/lib/rules/index.js

@@ -6,3 +6,3 @@ "use strict";
 });
-exports.commentRule = exports.codeRe = exports.commentRe = exports.createTocRule = exports.badgeRule = void 0;
+exports.linkTitleRe = exports.commentRule = exports.innerCodeRe = exports.codeRe = exports.commentRe = exports.createTocRule = exports.badgeRule = void 0;
 
@@ -32,4 +32,6 @@ var _util = require("util");
 exports.commentRe = commentRe;
-const codeRe = /```(`)?(\w+\n)?[\s\S]*?\n```\1/g;
+const codeRe = /^```(`)?(\w+)?\n[\s\S]*?\n```\1/gm;
 exports.codeRe = codeRe;
+const innerCodeRe = /`[^`\n]+?`/gm;
+exports.innerCodeRe = innerCodeRe;
 const commentRule = {
@@ -45,2 +47,4 @@ re: commentRe,
 exports.commentRule = commentRule;
+const linkTitleRe = /\[([^[\n]+?)\]\((t|#+)\)/gm;
+exports.linkTitleRe = linkTitleRe;
 //# sourceMappingURL=index.js.map

build/lib/rules/method-title.js

@@ -6,3 +6,3 @@ "use strict";
 });
-exports.default = exports.replacer = exports.methodTitleRe = exports.replaceTitle = void 0;
+exports.default = exports.methodTitleRe = exports.replacer = exports.replaceTitle = void 0;
 
@@ -46,4 +46,4 @@ var _util = require("util");
 exports.replaceTitle = replaceTitle;
-const methodTitleRe = /```(#+)( async)? (\w+)(?: => (.+)\n)?([\s\S]*?)```/g;
-exports.methodTitleRe = methodTitleRe;
+const re = /```(#+)( async)? (\w+)(?: => (.+)\n)?([\s\S]*?)```/g;
+exports.methodTitleRe = re;
 
@@ -62,3 +62,3 @@ const replacer = (match, level, isAsync, method, returnType, title) => {
 const titleRule = {
-  re: methodTitleRe,
+  re,
   replacement: replacer
@@ -65,0 +65,0 @@ };

build/lib/rules/table.js

@@ -6,3 +6,3 @@ "use strict";
 });
-exports.default = exports.replacer = void 0;
+exports.default = exports.tableRe = exports.replacer = void 0;
 
@@ -36,4 +36,6 @@ var _util = require("util");
 
+const re = /```table([\s\S]+?)```/mg;
+exports.tableRe = re;
 const tableRule = {
-  re: /```table([\s\S]+?)```/g,
+  re,
   replacement: replacer
@@ -40,0 +42,0 @@ };

build/lib/Toc.js

@@ -18,9 +18,52 @@ "use strict";
 
+var _build = require("restream/build");
+
+var _markers = require("./markers");
+
+var _table = require("./rules/table");
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 const re = /(?:^|\n) *(#+) *((?:(?!\n)[\s\S])+)\n/;
-const rre = (0, _.makeARegexFromRule)({
-  re
-});
 
+const getBuffer = async buffer => {
+  const {
+    title,
+    methodTitle,
+    code,
+    innerCode,
+    table,
+    linkTitle
+  } = (0, _markers.makeMarkers)({
+    title: /^ *#+.+/gm,
+    methodTitle: _methodTitle.methodTitleRe,
+    code: _rules.codeRe,
+    innerCode: _rules.innerCodeRe,
+    table: _table.tableRe,
+    linkTitle: _rules.linkTitleRe
+  });
+  const [cutTitle, cutLinkTitle, cutCode, cutMethodTitle, cutInnerCode, cutTable] = [title, linkTitle, code, methodTitle, innerCode, table].map(marker => {
+    const rule = (0, _markers.makeInitialRule)(marker);
+    return rule;
+  });
+  const [insertTitle, insertLinkTitle, insertMethodTitle, insertInnerCode, insertTable] = [title, linkTitle, methodTitle, innerCode, table].map(marker => {
+    const rule = (0, _markers.makeRule)(marker);
+    return rule;
+  });
+  const rs = new _build.Replaceable([cutTitle, cutInnerCode, cutLinkTitle, {
+    re: innerCode.regExp,
+
+    replacement() {
+      return '';
+    }
+
+  }, cutTable, cutMethodTitle, cutCode, _rules.commentRule, insertMethodTitle, insertTable, insertLinkTitle, insertInnerCode, insertTitle]);
+  const c = new _catchment.default({
+    rs
+  });
+  rs.end(buffer);
+  const b = await c.promise;
+  return b;
+};
+
 class Toc extends _stream.Transform {
@@ -38,14 +81,10 @@ /**
     this.skipLevelOne = skipLevelOne;
+    this.level = 0;
   }
 
-  _transform(buffer, enc, next) {
+  async _transform(buffer, enc, next) {
     let res;
-    const b = `${buffer}`.replace(new RegExp(_rules.commentRe, 'g'), '').replace(new RegExp(_rules.codeRe, 'g'), match => {
-      if (_.exactMethodTitle.test(match) || rre.test(match)) {
-        return match;
-      }
+    const b = await getBuffer(buffer); // create a single regex otherwise titles will always come before method titles
 
-      return ''; // ignore code blocks
-    });
-    const superRe = new RegExp(`(?:${re.source})|(?:${_methodTitle.methodTitleRe.source})`, 'g');
+    const superRe = new RegExp(`(?:${re.source})|(?:${_methodTitle.methodTitleRe.source})|(?:${_rules.linkTitleRe.source})`, 'g');
 
@@ -57,3 +96,7 @@ while ((res = superRe.exec(b)) !== null) {
 
-      if (res[1]) {
+      if (res[8] && res[9]) {
+        t = res[8];
+        level = res[9] != 't' ? res[9].length : this.level + 1;
+        link = (0, _.getLink)(t);
+      } else if (res[1]) {
         // normal title regex
@@ -63,4 +106,4 @@ const [, {
         }, title] = res;
-        level = length;
-        if (this.skipLevelOne && level == 1) continue;
+        this.level = length;
+        if (this.skipLevelOne && this.level == 1) continue;
         t = title;
@@ -71,4 +114,6 @@ link = (0, _.getLink)(title);
         try {
-          const l = res[3];
-          level = l.length;
+          const {
+            length
+          } = res[3];
+          this.level = length;
           const bb = res.slice(4, 6).filter(a => a).join(' ').trim();
@@ -92,2 +137,3 @@ const json = res[7] || '[]';
       let s;
+      if (!level) level = this.level;
 
@@ -97,3 +143,3 @@ if (level == 2) {
       } else {
-        const p = '  '.repeat(level - 2);
+        const p = '  '.repeat(Math.max(level - 2, 0));
         s = `${p}* ${heading}`;
@@ -106,3 +152,2 @@ }
 
-    re.lastIndex = -1;
     next();
@@ -109,0 +154,0 @@ }

CHANGELOG.md

@@ -0,1 +1,9 @@
+## 22 June 2018
+
+### 1.6.0
+
+- [feature] Embed the output of a Node.js module with `FORK`.
+- [feature] Link titles - add a link and reference it in the table of contents.
+- [fix] Don't process text in inner code (`inner`), testing, finer replacements order.
+
 ## 21 June 2018
@@ -2,0 +10,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A library to manage documentation, such as README, usage, man pages and changelog.",
@@ -43,7 +43,7 @@ "main": "build",
   "devDependencies": {
-    "@babel/cli": "7.0.0-beta.49",
-    "@babel/core": "7.0.0-beta.49",
-    "@babel/plugin-syntax-object-rest-spread": "7.0.0-beta.49",
-    "@babel/plugin-transform-modules-commonjs": "7.0.0-beta.49",
-    "@babel/register": "7.0.0-beta.49",
+    "@babel/cli": "7.0.0-beta.51",
+    "@babel/core": "7.0.0-beta.51",
+    "@babel/plugin-syntax-object-rest-spread": "7.0.0-beta.51",
+    "@babel/plugin-transform-modules-commonjs": "7.0.0-beta.51",
+    "@babel/register": "7.0.0-beta.51",
     "babel-plugin-transform-rename-import": "2.2.0",
@@ -59,3 +59,3 @@ "eslint": "4.19.1",
     "catchment": "2.0.1",
-    "pedantry": "1.0.0",
+    "pedantry": "1.0.1",
     "restream": "2.1.0",
@@ -62,0 +62,0 @@ "spawncommand": "2.0.1",

README.md

@@ -18,2 +18,4 @@ # documentary
   * [TOC Generation](#toc-generation)
+    * [TOC Titles](#toc-titles)
+      * [Specific Level](#specific-level)
   * [Tables Display](#tables-display)
@@ -27,2 +29,5 @@ * [Method Title](#method-title)
   * [Replacement Rules](#replacement-rules)
+    * [`%NPM: package-name%`](#npm-package-name)
+    * [`%TREE directory ...args%`](#tree-directory-args)
+    * [`%FORK(-lang)? module ...args%`](#fork-lang-module-args)
   * [Examples Placement](#examples-placement)
@@ -83,2 +88,10 @@ - [CLI](#cli)
 ```
+
+#### TOC Titles
+
+To be able to include a link to a specific position in the text (i.e., create an "anchor"), `documentary` supports a `TOC Titles` feature. Any text written as `[Toc Title](t)` will generate a relevant position in the table of contents. It will automatically detect the appropriate level and be contained inside the current section.
+
+This feature can be useful when presenting some data in a table in a section, but wanting to include a link to each row in the table of contents so that the structure is immediately visible.
+
+**<a name="specific-level">Specific Level</a>**: if required, the level can be specified with a number of `#` symbols, such as `[Specific Level](######)`.
 ### Tables Display
@@ -148,3 +161,3 @@
 
-Since comments found in `<!—— comment ——>` sections are not visible to users, they will be removed from the output document.
+Since comments found in `<!-- comment -->` sections are not visible to users, they will be removed from the output document.
 ### File Splitting
@@ -183,4 +196,5 @@
 | ---- | ----------- |
-| `%NPM: package-name%` | Adds an NPM badge, e.g., `[![npm version] (https://badge.fury.io/js/documentary.svg)] (https://npmjs.org/package/documentary)` |
-| `%TREE directory ...args` | Executes the `tree` command with the given arguments. If `tree` is not installed, warns and does not replace the match. |
+| <a name="npm-package-name">`%NPM: package-name%`</a> | Adds an NPM badge, e.g., `[![npm version] (https://badge.fury.io/js/documentary.svg)] (https://npmjs.org/package/documentary)` |
+| <a name="tree-directory-args">`%TREE directory ...args%`</a> | Executes the `tree` command with the given arguments. If `tree` is not installed, warns and does not replace the match. |
+| <a name="fork-lang-module-args">`%FORK(-lang)? module ...args%`</a> | Forks the Node.js process to execute the module using `child_process.fork`. The output is printed in the code block, with optionally given language. For example: `%FORK-json example.js -o%` |
 ### Examples Placement
@@ -287,10 +301,3 @@
 
-```sh
-yarn example/toc.js
-```
-
 ```fs
-$ NODE_DEBUG=doc yarn e example/toc.js
-$ node example example/toc.js
-DOC 13980: Reading /documentary/example/markdown.md
 - [Table Of Contents](#table-of-contents)
@@ -297,0 +304,0 @@ - [CLI](#cli)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

73364

increased by39.23%

Number of package files

30

increased by25%

Lines of code

693

increased by48.71%

Number of lines in readme file

309

increased by2.32%

Dependency changes

• + Addedpedantry@1.0.1(transitive)

• - Removedpedantry@1.0.0(transitive)

• Updatedpedantry@1.0.1