documentary
Advanced tools
A library to manage documentation, such as README, usage, man pages and changelog.
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 -DE documentary
TitlesThe doc client is available after installation. It can be used in a doc script of package.json, as follows:
{
"scripts": {
"doc": "doc documentary -o README.md"
}
}
The first argument, documentary is a path to a directory containing source documentation files, or a path to a single file to be processed, e.g., README-source.md.
Therefore, to produce an output README.md, the following command will be used:
yarn doc
When actively working on documentation, it is possible to use the watch mode with -w flag, or -p flag to also automatically push changes to a remote git repository, merging them into a single commit every time.
The processed README.md file will have a generated table of contents, markdown tables and neat titles for API method descriptions, as well as other possible features described in this section.
Table of contents are useful for navigation in a README document. When a %TOC% placeholder is found in the file, it will be replaced with an extracted structure. Titles appearing in comments and code blocks will be skipped.
By default, top level h1 headers written with # are ignored, but they can be added by passing -h1 CLI argument.
- [Table Of Contents](#table-of-contents)
- [CLI](#cli)
* [`-j`, `--jsdoc`: Add JSDoc](#-j---jsdoc-add-jsdoc)
- [API](#api)
- [Copyright](#copyright)
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.
Specific Level: if required, the level can be specified with a number of # symbols, such as [Specific Level](######).
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.
```table
[
["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 is possible to generate neat titles useful for API documentation with documentary. The method signature should be specified as a JSON array, where every member is an argument specified as an array. The first item in the argument array is the argument name, and the second one is type. Type can be either a string, or an object. If it is an object, each value in the object will be an array and first contain the property type, secondly - the default value. To mark a property as optional, the ? symbol can be used at the end. The third item is the short name for the table of contents (so that a complex object can be referenced to its type).
async runSoftware(path: string,config: {View: Container,actions: object,static?: boolean = true,render?: function,},): stringGenerated from
```#### async runSoftware => string
[
["path", "string"],
["config", {
"View": ["Container"],
"actions": ["object"],
"static?": ["boolean", true],
"render?": ["function"]
}, "Config"]
]
```
async runSoftware(path: string,): voidGenerated from
```#### async runSoftware
[
["path", "string"]
]
```
runSoftware(): stringGenerated from
```#### runSoftware => string
```
Since comments found in <!-- comment --> sections are not visible to users, they will be removed from the output document.
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:
documentary
├── 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
│ ├── 6-rules.md
│ ├── 7-examples.md
│ ├── 8-gif.md
│ ├── 9-type.md
│ ├── 91-typedef
│ │ ├── 1-js.md
│ │ ├── 2-readme.md
│ │ ├── 3-imports.md
│ │ ├── 4-schema.md
│ │ ├── 9-migration.md
│ │ └── index.md
│ └── index.md
├── 3-cli.md
├── 4-api
│ ├── 1-toc.md
│ └── index.md
├── footer.md
└── index.md
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) |
%TREE directory ...args% | Executes the tree command with the given arguments. If tree is not installed, warns and does not replace the match. |
%FORK(-lang)? module ...args% | 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% |
%FORKERR(-lang)? module ...args% | Same as %FORK% but will print the output of the stderr. |
documentary can be used to embed examples into the documentation. The example file needs to be specified with the following marker:
%EXAMPLE: example/example.js [, ../src => documentary] [, javascript]%
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 (or require calls). 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:
## API Method
This method allows to generate documentation.
%EXAMPLE: example/example.js, ../src => documentary, javascript%
And the example file examples/example.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()
})()
```
Whenever only a part of an example needs to be shown (but the full code is still needed to be able to run it), documentary allows to use start and end comments to specify which part to print to the documentation. It will also make sure to adjust the indentation appropriately.
import documentary from '../src'
import Catchment from 'catchment'
(async () => {
/* start example */
await documentary()
/* end example */
})()
await documentary()
The GIF rule will inserts a gif animation inside of a <detail> block. To highlight the summary with background color, <code> should be used instead of back-ticks. TOC title link also work inside the summary.
%GIF doc/doc.gif
Alt: Generating documentation.
Click to View: [<code>yarn doc</code>](t)
%
yarn doc
|
The actual html placed in the README looks like the one below:
<details>
<summary>Summary of the detail: <code>yarn doc</code></summary>
<table>
<tr><td>
<img alt="Alt: Generating documentation." src="doc/doc.gif" />
</td></tr>
</table>
</details>
Type DefinitionOften, it is required to document a type of an object, which methods can use. To display the information about type's properties in a table, the TYPE macro can be used. It allows to show all possible properties that an object can contain, show which ones are required, give examples and link them in the table of contents (disabled by default).
Its signature is as follows:
%TYPE addToToc(true|false)
<p name="propertyName" type="propertyType" required>
<d>Property Description.</d>
<d>Property Example.</d>
</p>
%
For example,
%TYPE
<p name="text" type="string" required>
<d>Display text. Required.</d>
<e>
```js
const q = {
text: 'What is your name',
}
```
</e>
</p>
<p name="validation" type="(async) function">
<d>A function which needs to throw an error if validation does not pass.</d>
<e>
```js
const q = {
text: 'What is your name',
validate(v) {
if (!v.length) throw new Error('Name is required.')
},
}
```
</e>
</p>
%
will display the following table:
| Property | Type | Description | Example |
|---|---|---|---|
text* | string | Display text. Required. |
|
validation | (async) function | A function which needs to throw an error if validation does not pass. |
|
When required to use the markdown syntax in tables (such as __, links, etc), an extra space should be left after the d or e tags like so:
%TYPE true
<p name="skipLevelOne" type="boolean">
<d>
Start the table of contents from level 2, i.e., excluding the `#` title.</d>
</p>
%
Otherwise, the content will not be processed by GitHub. However, it will add an extra margin to the content of the cell as it will be transformed into a paragraph.
Because examples occupy a lot of space which causes table squeezing on GitHub and scrolling on NPM, documentary allows to dedicate a special row to an example. It can be achieved by adding a row attribute to the e element, like so:
%TYPE
<p name="headers" type="object">
<d>Incoming headers returned by the server.</d>
<e row>
```json
{
"server": "GitHub.com",
"content-type": "application/json",
"content-length": "2",
"connection": "close",
"status": "200 OK"
}
```
</e>
</p>
%
In addition, any properties which do not contain examples will not have an example column at all.
| Property | Type | Description | Example |
|---|---|---|---|
body | string|object|Buffer | The return from the server. | |
headers | object | Incoming headers returned by the server. | |
| |||
statusCode | number | The status code returned by the server. | 200 |
Finally, when no examples which are not rows are given, there will be no Example heading.
%TYPE
<p name="data" type="object">
<d>Optional data to send to the server with the request.</d>
<e row>
```js
{
name: 'test',
}
```
</e>
</p>
<p name="method" type="string">
<d>What HTTP method to use to send data (only works when <code>data</code> is set).</d>
</p>
%
| Property | Type | Description |
|---|---|---|
data | object | Optional data to send to the server with the request. |
| ||
method | string | What HTTP method to use to send data (only works when data is set). |
@typedef OrganisationFor the purpose of easier maintenance of JSDoc @typedef declarations, documentary allows to keep them in a separate XML file, and then place compiled versions into both source code as well as documentation. By doing this, more flexibility is achieved as types are kept in one place but can be reused for various purposes across multiple files. It is different from TypeScript type declarations as documentary will generate JSDoc comments rather than type definitions which means that a project does not have to be written in TypeScript.
Types are kept in a separate xml file, for example:
<types>
<import name="ServerResponse" from="http" />
<type name="SetHeaders"
type="(res: ServerResponse) => any"
desc="Function to set custom headers on response." />
<type name="StaticConfig" desc="Options to setup `koa-static`.">
<prop string name="root">
Root directory string.
</prop>
<prop number name="maxage" default="0">
Browser cache max-age in milliseconds.
</prop>
<prop boolean name="hidden" default="false">
Allow transfer of hidden files.
</prop>
<prop string name="index" default="index.html">
Default file name.
</prop>
<prop opt type="SetHeaders" name="setHeaders">
Function to set custom headers on response.
</prop>
</type>
</types>
They are then included in both JavaScript source code and markdown documentation.
To include a compiled declaration into a source code, the following line should be placed in the .js file (where the types/static.xml file exists in the project directory from which the doc command will be run):
/* documentary types/static.xml */
For example, an unprocessed JavaScript file can look like this:
/* src/config-static.js */
import Static from 'koa-static'
/**
* Configure the middleware.
*/
function configure(config) {
const middleware = Static(config)
return middleware
}
/* documentary types/static.xml */
export default configure
Please note that the types marker must be placed before
export defaultis done (or justexport) as there's currently a bug in VS Code.
The file is then processed with doc src/config-static.js -g command and updated in place, unless - is given as an argument, which will print the output to stdout, or the path to the output file is specified. After the processing is done, the source code will be transformed to include all types specified in the XML file. This routine can be repeated whenever types are updated (unless the spread attribute was set, when the generated JSDoc of a function has to be removed by hand first).
/* src/config-static.js */
import Static from 'koa-static'
/**
* Configure the middleware.
*/
function configure(config) {
const middleware = Static(config)
return middleware
}
/* documentary types/static.xml */
/**
* @typedef {import('http').ServerResponse} ServerResponse
*
* @typedef {(res: ServerResponse) => any} SetHeaders Function to set custom headers on response.
*
* @typedef {Object} StaticConfig Options to setup `koa-static`.
* @prop {string} root Root directory string.
* @prop {number} [maxage=0] Browser cache max-age in milliseconds. Default `0`.
* @prop {boolean} [hidden=false] Allow transfer of hidden files. Default `false`.
* @prop {string} [index="index.html"] Default file name. Default `index.html`.
* @prop {SetHeaders} [setHeaders] Function to set custom headers on response.
*/
export default configure
@paramIn addition, JSDoc for any method that has an included type as one of its parameters will be updated to its expanded form so that a preview of options is available.
Therefore, a raw function JSDoc of a function written as
/**
* Configure the middleware.
* @param {StaticConfig} config Options to setup `koa-static`.
*/
function configure(config) {
const middleware = Static(config)
return middleware
}
will be expanded to include the properties of the type:
/**
* Configure the middleware.
* @param {StaticConfig} config Options to setup `koa-static`.
* @param {string} config.root Root directory string.
* @param {number} [config.maxage=0] Browser cache max-age in milliseconds. Default `0`.
* @param {boolean} [config.hidden=false] Allow transfer of hidden files. Default `false`.
* @param {string} [config.index="index.html"] Default file name. Default `index.html`.
* @param {SetHeaders} [config.setHeaders] Function to set custom headers on response.
*/
function configure(config) {
const middleware = Static(config)
return middleware
}
This makes it possible to see the properties of the argument to the configure function fully:
And the description of each property will be available when passing an argument to the function:
Compare that to the preview without JSDoc expansion:
To prevent the expansion, the noExpand attribute should be added to the type.
@paramMoreover, when the type of the type is just object, it also can be spread into a notation which contains its properties for even better visibility. To do that, the spread attribute must be added to the type definition in the xml file.
Again, a raw function with JSDoc:
/**
* Configure the middleware.
* @param {StaticConfig} config Options to setup `koa-static`.
*/
function configure(config) {
const middleware = Static(config)
return middleware
}
Can be re-written as spread notation of a type.
/**
* Configure the middleware.
* @param {{ root: string, maxage?: number, hidden?: boolean, index?: string, setHeaders?: SetHeaders }} config Options to setup `koa-static`.
* @param {string} config.root Root directory string.
* @param {number} [config.maxage=0] Browser cache max-age in milliseconds. Default `0`.
* @param {boolean} [config.hidden=false] Allow transfer of hidden files. Default `false`.
* @param {string} [config.index="index.html"] Default file name. Default `index.html`.
* @param {SetHeaders} [config.setHeaders] Function to set custom headers on response.
*/
function configure(config) {
const middleware = Static(config)
return middleware
}
The properties will be visible in the preview:
However, this method has one disadvantage as there will be no descriptions of the properties when trying to use them in a call to function:
Therefore, it must be considered what is the best for developers -- to see descriptions of properties when passing a configuration object to a function, but not see all possible properties, or to see the full list of properties, but have no visibility of what they mean.
To place a type definition as a table into a README file, the TYPEDEF snippet can be used, where the first argument is the path to the xml file containing definitions, and the second one is the name of the type to embed. Moreover, links to the type descriptions will be created in the table of contents using the TOC Titles, but to prevent this, the noToc attribute should be set for a type.
%TYPEDEF path/definitions.xml TypeName%
For example, using previously defined StaticConfig type from types/static.xml file, documentary will process the following markers:
%TYPEDEF types/static.xml ServerResponse%
%TYPEDEF types/static.xml SetHeaders%
%TYPEDEF types/static.xml StaticConfig%
or a single marker to include all types in order in which they appear in the xml file (doing this also allows to reference other types from properties):
%TYPEDEF types/static.xml%
and embed resulting type definitions:
import('http').ServerResponse ServerResponse
(res: ServerResponse) => any SetHeaders: Function to set custom headers on response.
StaticConfig: Options to setup koa-static.
| Name | Type | Description | Default |
|---|---|---|---|
| root* | string | Root directory string. | - |
| maxage | number | Browser cache max-age in milliseconds. | 0 |
| hidden | boolean | Allow transfer of hidden files. | false |
| index | string | Default file name. | index.html |
| setHeaders | SetHeaders | Function to set custom headers on response. | - |
A special import element can be used to import a type using VS Code's TypeScript engine. An import is just a typedef which looks like /** @typedef {import('package').Type} Type */. This makes it easier to reference the external type later in the file. However, it is not supported in older versions of VS Code.
| Original Source | Types Definition |
|---|---|
|
|
| Output | |
|
The XML file should have the following nodes and attributes:
| Node | Description | Attributes |
|---|---|---|
|
types | A single root element. | |
|
import | An imported type definition. |
|
|
type |
A |
|
|
prop |
Property of a |
|
A JavaScript file can be scanned for the presence of @typedef JSDoc comments, which are then extracted to a types.xml file. This can be done with the doc src/index.js -e types/index.xml command. This is primarily a tool to migrate older software to using types.xml files which can be used both for online documentation and editor documentation.
For example, types can be extracted from a JavaScript file which contains JSDoc in form of comments:
async function test() {
process.stdout.write('ttt')
}
/**
* @typedef {import('http').IncomingMessage} IncomingMessage
*/
/**
* @typedef {(m: IncomingMessage)} Test This is test function.
*
* @typedef {Object} SessionConfig Description of Session Config.
* @prop {string} key cookie key.
* @prop {number|'session'} [maxAge=86400000] maxAge in ms. `session` will result in a cookie that expires when session/browser is closed.
* @prop {boolean} [overwrite] Can overwrite or not. Default `true`.
* @prop {boolean} [httpOnly] httpOnly or not or not. Default `true`.
* @prop {boolean} [renew] Renew session when session is nearly expired, so we can always keep user logged in. Default `false`.
*/
export default test
When a description ends with Default `value`, the default value of a type can also be parsed from there.
<types>
<import name="IncomingMessage" from="http" />
<type name="Test" type="(m: IncomingMessage)" desc="This is test function." />
<type name="SessionConfig" desc="Description of Session Config.">
<prop string name="key">
cookie key.
</prop>
<prop type="number|'session'" name="maxAge" default="86400000">
maxAge in ms. `session` will result in a cookie that expires when session/browser is closed.
</prop>
<prop boolean name="overwrite" default="true">
Can overwrite or not.
</prop>
<prop boolean name="httpOnly" default="true">
httpOnly or not or not.
</prop>
<prop boolean name="renew" default="false">
Renew session when session is nearly expired, so we can always keep user logged in.
</prop>
</type>
</types>
The program is used from the CLI (or package.json script).
doc README-source.md [-o README.md] [-tgewp]
The arguments it accepts are:
| Flag | Meaning | Description |
|---|---|---|
-o path | Output Location | Where to save the processed README file. If not specified, the output is written to the stdout. |
-t | Only TOC | Only extract and print the table of contents. |
-g [path] | Generate Types | Insert @typedef JSDoc into JavaScript files. When no path is given, the files are updated in place, and when - is passed, the output is printed to stdout. |
-e [path] | Extract Types | Insert @typedef JSDoc into JavaScript files. When no path is given, the files are updated in place, and when - is passed, the output is printed to stdout. |
-w | Watch Mode | Watch mode: re-run the program when changes to the source file are detected. |
-p "commit message" | Automatic Push | Watch + push: automatically push changes to a remote git branch by squashing them into a single commit. |
-h1 | h1 In Toc | Include h1 headers in the table of contents. |
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
The programmatic use of the documentary is intended for developers who want to use this software in their projects.
Toc StreamToc is a transform stream which can generate a table of contents for incoming markdown data. For every title that the transform sees, it will push the appropriate level of the table of contents.
TocConfig TypeWhen creating a new Toc instance, it will accept the following configuration object.
| Property | Type | Description | Example |
|---|---|---|---|
skipLevelOne | boolean | Start the table of contents from level 2, i.e., excluding the # title. | For example, the following code:
will be compiled to when when |
constructor(config?: {skipLevelOne?: boolean = true,},): TocCreate a new instance of a Toc stream.
/* yarn example/toc.js */
import { Toc } from 'documentary'
import Catchment from 'catchment'
import { createReadStream } from 'fs'
(async () => {
try {
const md = createReadStream('example/markdown.md')
const rs = new Toc()
md.pipe(rs)
const { promise } = new Catchment({ rs })
const res = await promise
console.log(res)
} catch ({ stack }) {
console.log(stack)
}
})()
- [Table Of Contents](#table-of-contents)
- [CLI](#cli)
* [`-j`, `--jsdoc`: Add JSDoc](#-j---jsdoc-add-jsdoc)
- [API](#api)
- [Copyright](#copyright)
TitlesTitles written as blocks and underlined with any number of either === (for H1) and --- (for H2), will be also displayed in the table of contents. However, the actual title will appear on a single line.
#PRO
Underlined
`Titles`
---
As seen in the Markdown Cheatsheet.
zoroaster's masks.require call in addition to import statement.(c) Art Deco 2018
FAQs
Documentation Compiler To Generate The Table Of Contents, Embed Examples With Their Output, Make Markdown Tables, Maintain Typedefs For JavaScript And README, Watch Changes To Push, Use Macros And Prettify API Titles.
The npm package documentary receives a total of 204 weekly downloads. As such, documentary popularity was classified as not popular.
We found that documentary demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.