New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

documentary

Package Overview
Dependencies
Maintainers
1
Versions
118
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

documentary - npm Package Compare versions

Comparing version 1.0.1 to 1.1.0

build/bin/run.js
build/bin/run.js.map
build/lib/replace-stream.js
build/lib/replace-stream.js.map

43

build/bin/index.js
#!/usr/bin/env node
"use strict";
var _fs = require("fs");
var _argufy = _interopRequireDefault(require("argufy"));

@@ -8,3 +10,3 @@

var _toc = _interopRequireDefault(require("./toc"));
var _run = _interopRequireDefault(require("./run"));

@@ -16,17 +18,24 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

const {
source,
output,
toc,
replace,
out
watch
} = (0, _argufy.default)({
toc: 't',
replace: {
short: 'r',
source: {
command: true
},
toc: {
short: 't',
boolean: true
},
out: 'o'
watch: {
short: 'w',
boolean: true
},
output: 'o'
}, process.argv);
(async () => {
const doRun = async () => {
try {
if (toc) await (0, _toc.default)(toc, out, replace);
await (0, _run.default)(source, output, toc);
} catch ({

@@ -38,3 +47,19 @@ stack,

}
};
(async () => {
if (!source) {
console.log('Please specify an input file.'); // print usage
process.exit(1);
}
await doRun();
if (watch) {
(0, _fs.watchFile)(source, async () => {
await doRun();
});
}
})();
//# sourceMappingURL=index.js.map

10

build/index.js

@@ -7,3 +7,13 @@ "use strict";

exports.default = documentary;
Object.defineProperty(exports, "Toc", {
enumerable: true,
get: function () {
return _Toc.default;
}
});
var _Toc = _interopRequireDefault(require("./lib/Toc"));
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
/**

@@ -10,0 +20,0 @@ * This is the main package file.

17

build/lib/Toc.js

@@ -16,8 +16,10 @@ "use strict";

/**
* @param {Object} config
* @param {boolean} [config.skipLevelOne=true]
* A transform stream which will extract the titles in the markdown document and transform them into a markdown nested list with links.
* @param {Config} [config] Configuration object.
* @param {boolean} [config.skipLevelOne=true] Don't use the first title in the TOC (default `true`).
*/
constructor({
skipLevelOne = true
} = {}) {
constructor(config = {}) {
const {
skipLevelOne = true
} = config;
super();

@@ -54,4 +56,9 @@ this.skipLevelOne = skipLevelOne;

}
/**
* @typedef {Object} Config
* @property {boolean} [skipLevelOne=true] Don't use the first title in the TOC (default `true`).
*/
exports.default = Toc;
//# sourceMappingURL=Toc.js.map

6

CHANGELOG.md

@@ -0,1 +1,7 @@

## 15 June 2018
### 1.1.0
- [feature] parsing tables, `watch` mode,
## 12 June 2018

@@ -2,0 +8,0 @@

9

package.json
{
"name": "documentary",
"version": "1.0.1",
"version": "1.1.0",
"description": "A library to manage documentation, such as README, usage, man pages and changelog.",

@@ -15,6 +15,7 @@ "main": "build",

"dev": "NODE_DEBUG=doc node src/bin/register",
"doc": "NODE_DEBUG=doc node build/bin 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"
"build": "babel src --out-dir build --source-maps --ignore src/bin/register.js"
},

@@ -55,7 +56,7 @@ "bin": {

"dependencies": {
"argufy": "1.0.2",
"argufy": "1.1.1",
"catchment": "2.0.1",
"restream": "2.0.1",
"restream": "2.0.3",
"spawncommand": "2.0.1"
}
}

141

README-source.md

@@ -5,17 +5,10 @@ # documentary

`documentary` is a command-line tool and a library to manage documentation of Node.js packages.
`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.
<!-- such as README, usage, man pages and changelog. -->
<!-- It can be installed as a dependency, and run as a `package.json` script, using a `doc` command. -->
```sh
# install doc binary
npm i -g documentary
```
```sh
yarn add -E documentary
```
The features include generation of table of content, github live preview and title generator.
## Table of Contents

@@ -25,14 +18,51 @@

## CLI
## Installation & Usage
The `doc` client is available after installation.
The `doc` client is available after installation. It can be used in a `doc` script of `package.json`, as follows:
### `-t`, `--toc`: Generate TOC
```json
{
"scripts": {
"doc": "doc README-source.md -o README.md",
"dc": "git add README-source.md README.md && git commit -m ",
}
}
```
Table of Contents for the README page can be generated with `documentary` TOC generator.
Therefore, to run produce an output README.md, the following command will be used:
```sh
doc -t input-source.md [-r] [-o output.md]
yarn doc
```
The `dc` command is just a convenience script to commit both source and output files with a passed commit message, such as:
```sh
yarn dc 'add copyright'
```
### 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):
```json
{
"search.exclude": {
"**/README.md": true
}
}
```
## 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
Table of contents are useful for navigation the README document. When a `%TOC%` placeholder is found in the file, it will be replaced with an extracted structure.
<!-- ```sh
doc -t input-source.md [-r] [-o output.md]
``` -->
```md

@@ -46,4 +76,29 @@ - [Table Of Contents](#table-of-contents)

It will also include valid URLs used on GitHub to skip to the title when complex titles are given.
### Comments Stripping
Since comments found in `<!—— comment ——>` sections are not visible to users, they will be removed from the output document.
### Tables Display
To describe method arguments in a table, but prepare them in a more readable format, `documentary` will parse the code blocks with `table` language as a table. The blocks must be in `JSON` format and contain a single array of arrays which represent rows.
````m
```tаble
[
["arg", "description"],
["-f", "Display only free domains"],
["-z", "A list of zones to check"],
]
```
````
Result:
| arg | description |
| --- | ----------- |
| -f | Display only free domains |
| -z | A list of zones to check |
<!-- It will also include valid URLs used on GitHub to skip to the title when complex titles are given.
When `-r` or `--replace` argument is passed, the `%TOC%` placeholder in the file will be replaced with the generated table of contents. Passing `-o` allows to save the output to the file, otherwise it is printed into the _stdout_.

@@ -53,11 +108,11 @@

doc -t README-source.md -r -o README.md
```
``` -->
```
<!-- ```
Saved README.md from README-source.md
```
``` -->
The command will also strip any markdown comments (e,g., `<!—— comment ——>`).
<!-- The command will also strip any markdown comments (e,g., ). -->
### `-l`, `--live`: GitHub Live
<!-- ### `-l`, `--live`: GitHub Live

@@ -68,4 +123,30 @@ With GitHub live, `documentary` will monitor for any happening commits, push them to GitHub, extract the commit version, and refresh the page with open `README.md` file in Chrome browser. This allows to see the preview as it is viewed on GitHub.

doc live
``` -->
## CLI
The program is used from the CLI (or `package.json` script).
```sh
doc README-source.md [-o README.md] [-t] [-w]
```
The arguments it accepts are:
```table
[
["argument", "Description"],
["`-o`", "Where to save the processed `README` file. If not specified, the output is written to the `stdout`."],
["`-t`", "Only extract and print the table of contents."],
["`-w`", "Watch mode: re-run the program when changes to the source file are detected."]
]
```
When `NODE_DEBUG=doc` is set, the program will print debug information, e.g.,
```
DOC 80734: stripping comment
DOC 80734: could not parse the table
```
## API

@@ -93,11 +174,11 @@

### generateTitle(method: MethodDescriptor): string
<!-- ### generateTitle(method: MethodDescriptor): string
Generate a title for a method, for example:
#### `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`
`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` -->
### `toc(readable: ReadableStream): string`
### `new Toc()`
Generate table of contents.
Toc is a transform stream which can generate a table of contents.

@@ -116,10 +197,8 @@ ```js

// read the argument from yarn script, or execute against default readme file.
const [,,, arg2] = process.argv
const p = arg2 || path
;(async () => {
LOG('Reading %s', path)
const md = createReadStream(path)
const rs = new Toc()
md.pipe(rs)
;(async () => {
LOG('Reading %s', p)
const md = createReadStream(p)
const rs = new Toc(md)
const { promise } = new Catchment({

@@ -126,0 +205,0 @@ rs,

132

README.md

@@ -5,38 +5,66 @@ # documentary

`documentary` is a command-line tool and a library to manage documentation of Node.js packages.
`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.
```sh
# install doc binary
npm i -g documentary
```
```sh
yarn add -E documentary
```
The features include generation of table of content, github live preview and title generator.
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Installation & Usage](#installation--usage)
* [VS Code Settings](#vs-code-settings)
- [Features](#features)
* [TOC Generation](#toc-generation)
* [Comments Stripping](#comments-stripping)
* [Tables Display](#tables-display)
- [CLI](#cli)
* [`-t`, `--toc`: Generate TOC](#-t---toc-generate-toc)
* [`-l`, `--live`: GitHub Live](#-l---live-github-live)
- [API](#api)
* [generateTitle(method: MethodDescriptor): string](#generatetitlemethod-methoddescriptor-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`](#koa2jsxreducer-functionview-containeractions-objectstatic-boolean--truerender-function-function)
* [`toc(readable: ReadableStream): string`](#tocreadable-readablestream-string)
* [`new Toc()`](#new-toc)
## CLI
## Installation & Usage
The `doc` client is available after installation.
The `doc` client is available after installation. It can be used in a `doc` script of `package.json`, as follows:
### `-t`, `--toc`: Generate TOC
```json
{
"scripts": {
"doc": "doc README-source.md -o README.md",
"dc": "git add README-source.md README.md && git commit -m ",
}
}
```
Table of Contents for the README page can be generated with `documentary` TOC generator.
Therefore, to run produce an output README.md, the following command will be used:
```sh
doc -t input-source.md [-r] [-o output.md]
yarn doc
```
The `dc` command is just a convenience script to commit both source and output files with a passed commit message, such as:
```sh
yarn dc 'add copyright'
```
### 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):
```json
{
"search.exclude": {
"**/README.md": true
}
}
```
## 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
Table of contents are useful for navigation the README document. When a `%TOC%` placeholder is found in the file, it will be replaced with an extracted structure.
```md

@@ -50,38 +78,58 @@ - [Table Of Contents](#table-of-contents)

It will also include valid URLs used on GitHub to skip to the title when complex titles are given.
### Comments Stripping
When `-r` or `--replace` argument is passed, the `%TOC%` placeholder in the file will be replaced with the generated table of contents. Passing `-o` allows to save the output to the file, otherwise it is printed into the _stdout_.
Since comments found in `<!—— comment ——>` sections are not visible to users, they will be removed from the output document.
```sh
doc -t README-source.md -r -o README.md
```
### Tables Display
To describe method arguments in a table, but prepare them in a more readable format, `documentary` will parse the code blocks with `table` language as a table. The blocks must be in `JSON` format and contain a single array of arrays which represent rows.
````m
```tаble
[
["arg", "description"],
["-f", "Display only free domains"],
["-z", "A list of zones to check"],
]
```
Saved README.md from README-source.md
```
````
The command will also strip any markdown comments (e,g., `<!—— comment ——>`).
Result:
### `-l`, `--live`: GitHub Live
| arg | description |
| --- | ----------- |
| -f | Display only free domains |
| -z | A list of zones to check |
With GitHub live, `documentary` will monitor for any happening commits, push them to GitHub, extract the commit version, and refresh the page with open `README.md` file in Chrome browser. This allows to see the preview as it is viewed on GitHub.
## CLI
The program is used from the CLI (or `package.json` script).
```sh
doc live
doc README-source.md [-o README.md] [-t] [-w]
```
## API
The arguments it accepts are:
The programmatic use of the `documentary` is intended for developers who want to use this software in their projects.
| argument | Description |
| -------- | ----------- |
| `-o` | Where to save the processed `README` file. If not specified, the output is written to the `stdout`. |
| `-t` | Only extract and print the table of contents. |
| `-w` | Watch mode: re-run the program when changes to the source file are detected. |
### generateTitle(method: MethodDescriptor): string
When `NODE_DEBUG=doc` is set, the program will print debug information, e.g.,
Generate a title for a method, for example:
```
DOC 80734: stripping comment
DOC 80734: could not parse the table
```
#### `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`
## API
### `toc(readable: ReadableStream): string`
The programmatic use of the `documentary` is intended for developers who want to use this software in their projects.
Generate table of contents.
### `new Toc()`
Toc is a transform stream which can generate a table of contents.
```js

@@ -99,10 +147,8 @@ /* yarn example/toc.js */

// read the argument from yarn script, or execute against default readme file.
const [,,, arg2] = process.argv
const p = arg2 || path
;(async () => {
LOG('Reading %s', path)
const md = createReadStream(path)
const rs = new Toc()
md.pipe(rs)
;(async () => {
LOG('Reading %s', p)
const md = createReadStream(p)
const rs = new Toc(md)
const { promise } = new Catchment({

@@ -109,0 +155,0 @@ rs,

build/bin/register.js
build/bin/register.js.map
build/bin/index.js.map

Sorry, the diff of this file is not supported yet

build/index.js.map

Sorry, the diff of this file is not supported yet

build/lib/Toc.js.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc