documentary

documentary

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.

yarn add -E documentary

Table of Contents

• Table of Contents
• Installation & Usage
  • VS Code Settings
• Features
  • TOC Generation
  • Comments Stripping
  • Tables Display
• CLI
• API
  • new Toc()

Installation & Usage

The doc client is available after installation. It can be used in a doc script of package.json, as follows:

{
  "scripts": {
    "doc": "doc README-source.md -o README.md",
    "dc": "git add README-source.md README.md && git commit -m ",
  }
}

Therefore, to run produce an output README.md, the following command will be used:

yarn doc

The dc command is just a convenience script to commit both source and output files with a passed commit message, such as:

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):

{
  "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.

- [Table Of Contents](#table-of-contents)
- [CLI](#cli)
  * [`-j`, `--jsdoc`: Add JSDoc](#-j---jsdoc-add-jsdoc)
- [API](#api)
- [Copyright](#copyright)

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.

```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

CLI

The program is used from the CLI (or package.json script).

doc README-source.md [-o README.md] [-t] [-w]

The arguments it accepts are:

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

The programmatic use of the documentary is intended for developers who want to use this software in their projects.

new Toc()

Toc is a transform stream which can generate a table of contents.

/* yarn example/toc.js */
import { Toc } from 'documentary'
import Catchment from 'catchment'
import { createReadStream } from 'fs'
import { resolve } from 'path'
import { debuglog } from 'util'

const LOG = debuglog('doc')

const path = resolve(__dirname, 'markdown.md')

;(async () => {
  LOG('Reading %s', path)
  const md = createReadStream(path)
  const rs = new Toc()
  md.pipe(rs)

  const { promise } = new Catchment({
    rs,
  })
  const res = await promise
  console.log(res)
})()

yarn example/toc.js

$ 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)
- [CLI](#cli)
  * [`-j`, `--jsdoc`: Add JSDoc](#-j---jsdoc-add-jsdoc)
- [API](#api)
- [Copyright](#copyright)

---

(c) Art Deco Code 2018