documentary - npm Package Compare versions

Comparing version 1.3.1 to 1.4.0

build/bin/index.js

@@ -18,4 +18,2 @@ #!/usr/bin/env node
 
-// import runFile from './file'
-// import runDir from './dir'
 const LOG = (0, _util.debuglog)('doc');
@@ -86,9 +84,10 @@ const DEBUG = /doc/.test(process.env.NODE_DEBUG);
     DEBUG ? LOG(stack) : console.log(message);
-  } // if (watch) {
-  //   watchFile(source, async () => {
-  //     await doRun()
-  //   })
-  // }
+  }
 
+  if (_watch) {
+    (0, _fs.watch)(_source, async () => {
+      await doc(_source, _output, _toc);
+    });
+  }
 })();
 //# sourceMappingURL=index.js.map

build/lib/dir-stream.js

@@ -14,2 +14,3 @@ "use strict";
 
+// this needs to go in `wrote` once it's rewritten
 const readFile = (path, name) => {
@@ -16,0 +17,0 @@ const p = (0, _path.resolve)(path, name);

build/lib/index.js

@@ -6,8 +6,4 @@ "use strict";
 });
-exports.titleRule = exports.methodTitleRe = exports.titleReplacer = exports.replaceTitle = exports.tableRule = exports.getLink = void 0;
+exports.getLink = void 0;
 
-var _util = require("util");
-
-const LOG = (0, _util.debuglog)('doc');
-
 const getLink = title => {
@@ -19,80 +15,2 @@ 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

@@ -10,28 +10,17 @@ "use strict";
 
-var _util = require("util");
+var _rules = require("./rules");
 
-var _ = require(".");
+var _table = _interopRequireDefault(require("./rules/table"));
 
-var _rules = require("./rules");
+var _methodTitle = _interopRequireDefault(require("./rules/method-title"));
 
-const LOG = (0, _util.debuglog)('doc');
+var _example = _interopRequireDefault(require("./rules/example"));
 
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
 function createReplaceStream(toc) {
-  const s = (0, _restream.replaceStream)([{
-    re: /<!--[\s\S]*?-->\n*/g,
-
-    replacement() {
-      LOG('stripping comment');
-      return '';
-    }
-
-  }, {
-    re: /^%TOC%$/gm,
-    replacement: toc
-  }, {
-    re: /```table([\s\S]+?)```/g,
-    replacement: _.tableRule
-  }, _.titleRule, _rules.badgeRule]);
+  const tocRule = (0, _rules.createTocRule)(toc);
+  const s = new _restream.Replaceable([_rules.commentRule, tocRule, _rules.badgeRule, _table.default, _methodTitle.default, _example.default]);
   return s;
 }
 //# sourceMappingURL=replace-stream.js.map

build/lib/Toc.js

@@ -12,6 +12,6 @@ "use strict";
 
-var _fs = require("fs");
-
 var _ = require(".");
 
+var _methodTitle = require("./rules/method-title");
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
@@ -37,3 +37,3 @@
     let res;
-    const rre = new RegExp(`(?:${re.source})|(?:${_.methodTitleRe.source})`, 'g');
+    const rre = new RegExp(`(?:${re.source})|(?:${_methodTitle.methodTitleRe.source})`, 'g');
 
@@ -66,3 +66,3 @@ while ((res = rre.exec(buffer)) !== null) {
           });
-          const fullTitle = (0, _.replaceTitle)(...res.slice(3)).replace(/^#+ +/, '');
+          const fullTitle = (0, _methodTitle.replaceTitle)(...res.slice(3)).replace(/^#+ +/, '');
           link = (0, _.getLink)(fullTitle);
@@ -69,0 +69,0 @@ t = `\`${b}(${s.join(', ')})${res[6] ? `: ${res[6]}` : ''}\``;

CHANGELOG.md

@@ -0,1 +1,8 @@
+## 20 June 2018
+
+### 1.4.0
+
+- [feature] examples placement
+- [fix] re-enable watch mode
+
 ## 18 June 2018
@@ -2,0 +9,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "A library to manage documentation, such as README, usage, man pages and changelog.",
@@ -58,3 +58,3 @@ "main": "build",
     "catchment": "2.0.1",
-    "restream": "2.0.3",
+    "restream": "2.1.0",
     "spawncommand": "2.0.1",
@@ -61,0 +61,0 @@ "wrote": "1.4.0"

README.md

@@ -26,2 +26,5 @@ # documentary
   * [Replacement Rules](#replacement-rules)
+  * [Examples Placement](#examples-placement)
+- [API Method](#api-method)
+- [API Method](#api-method)
 - [CLI](#cli)
@@ -178,2 +181,49 @@ - [API](#api)
 | `%NPM: package-name%` | Adds an NPM badge, e.g., `[![npm version] (https://badge.fury.io/js/documentary.svg)] (https://npmjs.org/package/documentary)` |
+### Examples Placement
+
+`documentary` can be used to embed examples into the documentation. The example file needs to be specified with the following marker:
+
+```
+%EXAMPLE: examples/example.js, ../src => documentary%
+```
+
+The first argument is the path to the example relative to the working directory of where the command was executed (normally, the project folder). The second optional argument is the replacement for the `import` statements. The third optional argument is the markdown language to embed the example in and will be determined from the example extension if not specified.
+
+Given the documentation section:
+
+```md
+## API Method
+
+This method allows to generate documentation.
+
+%EXAMPLE: examples/example.js, ../src => documentary, javascript%`
+```
+
+And the example file `examples/example.js`
+
+```js
+import documentary from '../src'
+import Catchment from 'catchment'
+
+(async () => {
+  await documentary()
+})()
+```
+
+The program will produce the following output:
+
+````
+## API Method
+
+This method allows to generate documentation.
+
+```javascript
+import documentary from 'documentary'
+import Catchment from 'catchment'
+
+(async () => {
+  await documentary()
+})()
+```
+````
 ## CLI
@@ -180,0 +230,0 @@

No alert changes

Improved metrics

Total package byte prevSize

50148

increased by5.11%

Number of package files

26

increased by18.18%

Lines of code

459

increased by3.15%

Number of lines in readme file

302

increased by19.84%

Number of low supply chain risk alerts

4

decreased by-33.33%

Dependency changes

• + Addedrestream@2.1.0(transitive)

• - Removedrestream@2.0.3(transitive)

• Updatedrestream@2.1.0