documentary - npm Package Compare versions

Comparing version 1.2.0 to 1.3.0

build/bin/index.js

@@ -8,2 +8,4 @@ #!/usr/bin/env node
 
+var _wrote = require("wrote");
+
 var _util = require("util");
@@ -13,11 +15,15 @@
 
+var _dirStream = _interopRequireDefault(require("../lib/dir-stream"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
+// import runFile from './file'
+// import runDir from './dir'
 const LOG = (0, _util.debuglog)('doc');
 const DEBUG = /doc/.test(process.env.NODE_DEBUG);
 const {
-  source,
-  output,
-  toc,
-  watch
+  source: _source,
+  output: _output,
+  toc: _toc,
+  watch: _watch
 } = (0, _argufy.default)({
@@ -36,16 +42,5 @@ source: {
   output: 'o'
-}, process.argv);
+});
 
-const doRun = async () => {
-  try {
-    await (0, _run.default)(source, output, toc);
-  } catch ({
-    stack,
-    message
-  }) {
-    DEBUG ? LOG(stack) : console.log(message);
-  }
-};
-
-(async () => {
+const doc = async (source, output, toc) => {
   if (!source) {
@@ -57,10 +52,45 @@ console.log('Please specify an input file.'); // print usage
 
-  await doRun();
+  let stream;
 
-  if (watch) {
-    (0, _fs.watchFile)(source, async () => {
-      await doRun();
-    });
+  try {
+    const {
+      content
+    } = await (0, _wrote.readDirStructure)(source);
+    stream = (0, _dirStream.default)(source, content);
+  } catch (err) {
+    const {
+      code
+    } = err;
+
+    if (code == 'ENOTDIR') {
+      stream = (0, _fs.createReadStream)(source);
+    } else {
+      throw err;
+    }
   }
+
+  await (0, _run.default)(stream, output, toc);
+};
+
+(async () => {
+  try {
+    await doc(_source, _output, _toc);
+  } catch ({
+    stack,
+    message,
+    code
+  }) {
+    if (code == 'ENOENT') {
+      console.log('File %s does not exist', _source);
+      process.exit(2);
+    }
+
+    DEBUG ? LOG(stack) : console.log(message);
+  } // if (watch) {
+  //   watchFile(source, async () => {
+  //     await doRun()
+  //   })
+  // }
+
 })();
 //# sourceMappingURL=index.js.map

build/bin/run.js

@@ -10,4 +10,2 @@ "use strict";
 
-var _util = require("util");
-
 var _fs = require("fs");
@@ -17,15 +15,14 @@
 
+var _stream = require("stream");
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-const LOG = (0, _util.debuglog)('doc');
-
-const replaceFile = (path, toc, out) => {
-  const rs = (0, _fs.createReadStream)(path);
+const replaceFile = (stream, toc, out) => {
   const s = (0, _replaceStream.default)(toc);
   const ws = out ? (0, _fs.createWriteStream)(out) : process.stdout;
-  rs.pipe(s).pipe(ws);
+  stream.pipe(s).pipe(ws);
 
   if (out) {
     ws.on('close', () => {
-      console.log('Saved %s from %s', out, path);
+      console.log('Saved %s', out);
     });
@@ -35,12 +32,13 @@ }
 /**
- * @param {string} path
- * @param {string} [out]
- * @param {string} [out]
- * @param {boolean} [toc]
+ * @param {Readable} stream A readable stream.
+ * @param {string} [out] Path to the output file.
+ * @param {boolean} [toc] Just print the TOC.
  */
 
 
-async function run(path, out, toc) {
-  LOG('reading %s', path);
-  const t = await (0, _Toc.getToc)(path);
+async function run(stream, out, toc) {
+  const pt = new _stream.PassThrough();
+  pt.pause();
+  stream.pipe(pt);
+  const t = await (0, _Toc.getToc)(stream);
 
@@ -52,4 +50,5 @@ if (toc) {
 
-  replaceFile(path, t, out);
+  pt.resume();
+  replaceFile(pt, t, out);
 }
 //# sourceMappingURL=run.js.map

build/lib/replace-stream.js

@@ -14,2 +14,4 @@ "use strict";
 
+var _rules = require("./rules");
+
 const LOG = (0, _util.debuglog)('doc');
@@ -32,5 +34,5 @@
     replacement: _.tableRule
-  }, _.titleRule]);
+  }, _.titleRule, _rules.badgeRule]);
   return s;
 }
 //# sourceMappingURL=replace-stream.js.map

build/lib/Toc.js

@@ -95,6 +95,5 @@ "use strict";
 
-const getToc = async path => {
-  const md = (0, _fs.createReadStream)(path);
+const getToc = async stream => {
   const rs = new Toc();
-  md.pipe(rs);
+  stream.pipe(rs);
   const {
@@ -101,0 +100,0 @@ promise

CHANGELOG.md

@@ -0,1 +1,8 @@
+## 18 June 2018
+
+### 1.3.0
+
+- [feature] splitting topics into folders, npm badge replace rule
+- [doc] split into files in the `README` directory
+
 ## 15 June 2018
@@ -2,0 +9,0 @@

package.json

 {
   "name": "documentary",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A library to manage documentation, such as README, usage, man pages and changelog.",
@@ -15,3 +15,3 @@ "main": "build",
     "dev": "NODE_DEBUG=doc node src/bin/register",
-    "doc": "yarn dev README-source.md -o README.md",
+    "doc": "yarn dev README -o README.md",
     "start": "node build/bin",
@@ -57,7 +57,8 @@ "example/": "yarn e example/example.js",
   "dependencies": {
-    "argufy": "1.1.1",
+    "argufy": "1.1.2",
     "catchment": "2.0.1",
     "restream": "2.0.3",
-    "spawncommand": "2.0.1"
+    "spawncommand": "2.0.1",
+    "wrote": "1.4.0"
   }
 }

README.md

 # documentary
 
-[![npm version](https://badge.fury.io/js/documentary.svg)](https://badge.fury.io/js/documentary)
+[![npm version](https://badge.fury.io/js/documentary.svg)](https://npmjs.org/package/documentary)
 
@@ -11,5 +11,5 @@ `documentary` is a command-line tool and a library to manage documentation of Node.js packages. Due to the fact that complex `README` files are harder to maintain, `documentary` serves as a pre-processor of documentation.
 
-## Table of Contents
+## Table Of Contents
 
-- [Table of Contents](#table-of-contents)
+- [Table Of Contents](#table-of-contents)
 - [Installation & Usage](#installation--usage)
@@ -19,3 +19,2 @@ * [VS Code Settings](#vs-code-settings)
   * [TOC Generation](#toc-generation)
-  * [Comments Stripping](#comments-stripping)
   * [Tables Display](#tables-display)
@@ -26,2 +25,5 @@ * [Method Title](#method-title)
     * [`runSoftware(): string`](#runsoftware-string)
+  * [Comments Stripping](#comments-stripping)
+  * [File Splitting](#file-splitting)
+  * [Replacement Rules](#replacement-rules)
 - [CLI](#cli)
@@ -55,6 +57,5 @@ - [API](#api)
 ```
-
 ### VS Code Settings
 
-It might be confusing to have a source and ouput `README.md` file, therefore to prevent errors, the following snippet can be used to hide the compiled file from VS Code search (update the `.vscode/settings.json` file):
+It might be confusing to have a source and output `README.md` file, therefore to prevent errors, the following snippet can be used to hide the compiled file from VS Code search (update the `.vscode/settings.json` file):
 
@@ -68,7 +69,5 @@ ```json
 ```
-
 ## Features
 
 The processed `README-source.md` file will have a generated table of contents, markdown tables and neat titles for API method descriptions.
-
 ### TOC Generation
@@ -85,7 +84,2 @@
 ```
-
-### Comments Stripping
-
-Since comments found in `<!—— comment ——>` sections are not visible to users, they will be removed from the output document.
-
 ### Tables Display
@@ -154,3 +148,37 @@
 ````
+### Comments Stripping
 
+Since comments found in `<!—— comment ——>` sections are not visible to users, they will be removed from the output document.
+### File Splitting
+
+`documentary` can read a directory and put files together into a single `README` file. The files will be sorted in alphabetical order, and their content merged into a single stream. The `index.md` and `footer.md` are special in this respect, so that the `index.md` of a directory will always go first, and the `footer.md` will go last.
+
+Example structure used in this project:
+
+```m
+README
+├── 1-installation-and-usage
+│   ├── 1-vs-code.md
+│   └── index.md
+├── 2-features
+│   ├── 1-TOC-generation.md
+│   ├── 2-table-display.md
+│   ├── 3-method-title.md
+│   ├── 4-comment-stripping.md
+│   ├── 5-file-splitting.md
+│   └── index.md
+├── 3-cli.md
+├── 4-api
+│   ├── 1-toc.md
+│   └── index.md
+├── footer.md
+└── index.md
+```
+### Replacement Rules
+
+There are some built-in rules for replacements.
+
+| Rule | Description |
+| ---- | ----------- |
+| `%NPM: package-name%` | Adds an NPM badge, e.g., `[![npm version] (https://badge.fury.io/js/documentary.svg)] (https://npmjs.org/package/documentary)` |
 ## CLI
@@ -178,7 +206,5 @@
 ```
-
 ## API
 
 The programmatic use of the `documentary` is intended for developers who want to use this software in their projects.
-
 ### `new Toc()`
@@ -229,3 +255,2 @@
 
-
 ---
@@ -232,0 +257,0 @@

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

47600

increased by3.8%

Number of package files

22

increased by15.79%

Lines of code

445

increased by24.65%

Number of lines in readme file

252

increased by11.01%

Worsened metrics

Dependency count

5

increased by25%

Number of low supply chain risk alerts

6

increased by20%

Dependency changes

• + Addedwrote@1.4.0

• + Addedargufy@1.1.2(transitive)

• + Addedclean-stack@1.3.0(transitive)

• + Addederotic@0.2.0(transitive)

• + Addedmakepromise@1.1.1(transitive)

• + Addedrestream@1.2.0(transitive)

• + Addedwrote@1.4.0(transitive)

• - Removedargufy@1.1.1(transitive)

• Updatedargufy@1.1.2