documentary
Advanced tools
A Documentation Pre-processor 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.
Documentary is a command-line tool to manage documentation of Node.JS packages of any size. Due to the fact that there is usually a lot of manual labour involved in creating and keeping up-to-date a README document, such as copying examples and the output they produce, there is a need for software that can help automate the process and focus on what is really important, i.e., documenting the features. Documentary serves as a pre-processor of documentation and enhances every area of the task of making available quality docs for Node.JS (and other languages) packages for fellow developers.
yarn add -D documentary
This section has a quick look at the best features available in Documentary and how they help the documentation process.
| Feature | Description | Advantages |
|---|---|---|
| Tables Of Contents | Compiles an accurate table of contents for the content. | 1. Makes the structure of the document immediately visible to the reader. 2. Allows to navigate across the page easily. 3. Shows problems with incorrect levels structure which otherwise might not be visible. 4. Allows to place anchor links available from the TOC at any level in any place of the README. 5. Can insert section breaks which visually divide the content and allow to navigate back to the top. |
| Examples | Allows to embed the source code into documentation. | 1. Increases productivity by eliminating the need to copy and paste the source code manually. 2. Developers can run examples as Node.js scripts to check that they are working correctly and debug them. 3. Examples can also be forked (see below). 4. It is possible to imports and requires such as ../src to be displayed as the name of the package. |
| Forks | Makes it possible to run an example and embed its stdout and stderr output directly into documentation. Supports import and export statements without Babel. Allows to save cache for faster re-runs. | 1. Enhances productivity by eliminating the need to copy and paste the output by hand. 2. Makes sure the output is always up-to-date with the documented one. 3. Will make it visible if a change to the code base lead to a different output (implicit regression testing). 4. Supports optional caching, so that programs don't have to be re-run each time a change to documentation in a different place is made. 5. Forked modules can use import and export statements natively, making it very easy to document the output of examples written in modern syntax. 6. Ensures that examples are actually working. 7. Can print usage of CLI tools by forking them with -h command. |
| JSX Components | Performs the compilation of custom-defined JSX components into markdown code. | 1. Lets to define custom components and reuse them across documentation where needed. 2. Provides a modern syntax to combine markdown and JavaScript. 3. When documentation written in HTML files, the components are documented with web-components.json file for the VSCode which will provide autosuggestions for the arguments of the component. |
| Tables | Compiles tables from arrays without having to write html or markdown. | 1. Removes the need to manually build tables either by hand, online or using other tools. 2. Provides table macros to reduce repetitive information and substitute only the core data into templates. |
| Macros | Reuses a defined template to place the data into placeholders. | 1. Removes the need to copy-paste patterns to different places and change data manually. 2. Maintains an up-to-date version of the template without having to change it everywhere. 3. Reduces the cluttering of the source documentation by noise and helps to focus on important information. |
| Live Push | Detects changes to the source documentation files, re-compiles the output README.md and pushes to the remote repository. | 1. The preview is available on-line almost immediately after a change is made. 2. Allows to skip writing a commit message and the push command every time a change is made. |
| Typedefs | Maintains a types.xml file to place types definition in it, available both for source code and documentation. | 1. Keeps the types declarations in one place, allowing to quickly update it both in JavaScript JSDoc, and in markdown README. 2. Automatically constructs type tables for documentation. 3. Expands the JSDoc config (options) argument for other developers to have a quick glance at possible options when calling a function. 4. Links all types across the whole documentation for quick navigation. 5. If the types.xml file or directory is published, other packages can embed it into documentation also, by using Documentary. |
| API Method Titles | Creates good-looking headers for methods. | 1. By writing each argument on new line, makes it easier to understand the signature of a function. 2. Can maintain a separate title for the table of contents to keep things simple there. |
Type Definition
Titles
The 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.
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 has 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.
Level TOC Titles: if required, the level can be specified with a number of # symbols, such as [Specific Level](###).
A section break is a small image in the center of the page which indicates the end of a section. With larger sections which also include sub-sections, this feature can help to differentiate when the topic finishes and another one starts. They can also be used to navigate back to the table of contents, or a specified location.
At the moment, there is support for pre-installed section breaks. In future, more support of custom images will be included.
To insert a section brake, the following marker is used:
%~[, number[, attributes]]%
For example:
%~%
%~ 15%
%~ -1%
%~ href="https://hello.world" width="200"%
<p align="center"><a href="#table-of-contents"><img src="/.documentary/section-breaks/0.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src="/.documentary/section-breaks/15.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src="/.documentary/section-breaks/-1.svg?sanitize=true"></a></p>
<p align="center"><a href="#table-of-contents"><img src="/.documentary/section-breaks/16.svg?sanitize=true" href="https://hello.world" width="200"></a></p>
There are 23 available section breaks which will be inserted in incremental order in the document. When the end of the list is reached, the count restarts. There are also 3 ending breaks which can be inserted at the end and do not participate in the rotation, so that they must be inserted manually. To select a specific image, its number can be given.
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
|---|---|---|---|---|---|---|---|---|---|---|---|
 |  |  |  |  |  |  |  |  |  |  |  |
| 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | |
 |  |  |  |  |  |  |  |  |  |  |
| -1 | -2 | -3 |
|---|---|---|
 |  |  |
By default, the section brake will link to the table of contents, however this can be changed by setting the href attribute. The images are also SVGs therefore it is possible to give them any width via the width attribute and they will stretch without any loss of quality. Documentary will copy images from its source code to the .documentary/section-breaks directory in the repository. To control the destination, set the to attribute on section breaks.
One of the most common problem with markdown is that it is hard to write tables. They must be written either as html, or as markdown, which is troublesome and requires effort. Although there are online tools to build markdown tables, with Documentary the process is even simpler: the data just needs to be put into a JSON array.
To describe tabular data (for example, a CLI tool arguments) in a table, but prepare them in a more readable format, Documentary allows to write code blocks with the table language to be converted into a markdown table. The content of 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 |
Whenever there's a pattern for presenting data in a table, such as that input fields can be mapped to output columns, a table macro can be defined. The example below defines a macro to print a row containing a link, logo and description of a company. It is then used in a table, where only the actual values are entered, relying on Documentary to substitute them in the template.
%TABLE-MACRO Company
<a href="$2"></a>, $4, $5\, $6
%
```table Company
[
["Company", "Tag Line", "Evaluation & Exit"],
[
"VWO", "https://vwo.com", "vwo.png", "A/B Testing and Conversion Optimization Platform™", "$10m", "2018"
]
]
```
| Company | Tag Line | Evaluation & Exit |
| --------------------------------------------------------------- | ------------------------------------------------- | ----------------- |
| <a href="https://vwo.com"></a> | A/B Testing and Conversion Optimization Platform™ | $10m, 2018 |
The values in the macro need to be separated with , which allows to substitute them into the correct column of the table row. When a , needs to be used as part of the column in the macro, it can be escaped with \ such as \, as shown in the last column of the example.
| Company | Tag Line | Evaluation & Exit |
|---|---|---|
 | A/B Testing and Conversion Optimization Platform™ | $10m, 2018 |
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%
> JS paths will be resolved automatically:
%EXAMPLE: example/example, ../src => documentary%
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()
})()
```
> JS paths will be resolved automatically:
```js
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()
When placing examples, it is important to show the output that they produce. This can be achieved using the FORK marker.
%FORK(-lang)? module ...args%
It will make Documentary fork a Node.JS module using the child_process.fork function. The output is printed in a code block, with optionally given language. If the process cleared lines with \r, the output will be adjusted to account for that to be displayed like it would be in the terminal. The environment variables will be inherited from the parent doc process.
| Markdown | JavaScript |
|---|---|
|
|
| Output | |
|
By default, the FORK marker will print the stdout output. To print the stderr output, there is the FORKERR marker.
%FORKERR(-lang)? module ...args%
It works exactly the same as %FORK% but will print the output of the process's stderr stream.
| Markdown | JavaScript |
|---|---|
|
|
| Output | |
|
The output of forks will be cached in the .documentary/cache directory. When compiling documentation, Documentary will check for the presence of cache, check the mtime of the module and if it is the same as cached, analyse module's dependencies to see if any of them had changes (updates to package dependencies' versions, changes to source files). When the cache is matched, no forking will take place and the value will be taken from the saved outputs. To explicitly prevent caching on a particular FORK marker, it should be prefixed with !: %!FORK module arg1 arg2%. To disable caching across all forks, the -c option can be passed to the CLI. Even if cache is disabled, the output will be saved so that when Documentary is run next time, the latest known output is placed instantly.
Documentary is able to fork modules that use import and export without the developer having to write a proxy file that would otherwise require @babel/register. It was made possible with ÀLaMode regex-based transpiler that will update the import/export statements on-the-fly. If there are any problems while using this feature, it can be disabled with the _ symbol: %_FORK module arg1 arg2%.
Documentary can generate neat titles useful for API documentation. The method signature should be specified in a JSON array, where every member is an argument written as an array containing its name and type. The type can be either a string, or an object.
For object types, each value is an array which contains the property type and its default value. To mark a property as optional, the ? symbol can be used at the end of the key.
The last item in the argument array is used when the argument is an object and is a short name to be place in 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
```
runSoftware(): voidGenerated from
```### runSoftware
```
Documentary lets users define their custom components in the .documentary folder both in the project directory and the user's home directory. The components are written using JSX syntax and exported as named functions from jsx files. The properties the component receives are extracted from the markdown syntax and passed to the hyperscript constructor (from preact).
For example, the user can define their own component in the following way:
import read from '@wrote/read'
/**
* Display the sponsor information.
*/
export const Sponsor = ({
name, link, image, children,
}) => {
return <table>
<tr/>
<tr>
<td align="center">
<a href={link}>
<img src={image} alt={name}/>
</a><br/>
Sponsored by <a href={link}>{name}</a>.
</td>
</tr>
{children && <tr><td>{children}</td></tr>}
</table>
}
/**
* The async component to print the source of the document.
*/
export const Source = async ({ src }) => {
const res = await read(src)
const e = src.split('.')
const ext = e[e.length - 1]
return `\`\`\`${ext}
${res}
\`\`\``
}
And then invoke it in the documentation:
<Sponsor name="Tech Nation Visa Sucks"
link="https://www.technation.sucks"
image="sponsor.gif">
Get In Touch To Support Documentary
</Sponsor>
The result will be rendered HTML:
Sponsored by Tech Nation Visa Sucks . |
| Get In Touch To Support Documentary |
The components can be rendered asynchronously when the component returns a promise. Documentary will wait for the promise to resolve before attempting to render JSX into HTML. Only the root component can be asynchronous, and if it uses other components in its JSX, they must be synchronous.
<Source src="src/index.js" />
If a component returns just a string without actually using JSX, then it is pasted into the code as is, see the Source example.
To receive access to the autosuggestions powered by VSCode's customData implementation of web-components.json standard, documentation files need to be written in HTML file format, and the .vscode/settings.json has to be updated to include the html.experimental.customData property as shown below:
{
"html.experimental.customData": [
"./node_modules/documentary/web-components.json"
]
}
Then, Documentary's components will be available when pressing CMD + SPACE in the editor.
<shell command="echo" language="fs">
HELLO WORLD!
EXAMPLE !@£
</shell>
$ echo "HELLO WORLD!" "EXAMPLE !@£"
HELLO WORLD! EXAMPLE !@£
There are a number of built-in components at the moment.
<shell command?="">Either uses spawn to spawn a command and pass arguments to it, or exec to get the result of a more complex operations such as piping to other commands reachable from shell.
Usage:
<shell command="echo"/>
<shell command="echo">ABC</shell>
<shell command="echo">
Hello World
example123
</shell>
<shell>
(echo abc; sleep 1; echo def; sleep 1; echo ghi) | node consume2.js
</shell>
<shell noTrim>
(echo abc;) | node consume2.js
</shell>
Executes a command as if by the user from the terminal, i.e., $ echo example and shows its output after printing the command like
```{language}
$ {command}
```
```{language = sh}
{output}
```
ShellProps: Options for the Shell component. TODO: pass options.
| Name | Type | Description | Default |
|---|---|---|---|
| command | string | The command to execute using the child_process. If the command is not passed, the children will be used to pass to exec, e.g., (echo abc; sleep 1; echo def; sleep 1; echo ghi) | node consume.js. | - |
| language | string | The markdown language of the output. | sh |
| err | boolean | Whether to print STDERR instead of STDOUT (todo: make print both). | false |
| children | string | The arguments to the program each on new line. | - |
| noTrim | boolean | Whether to disable trim before printing the output. | false |
If the command is not passed, the children will be read and executed by the child_process.exec method. For example, with the following simple receiver:
process.stdin.on('data', d => console.log(`${d}`))
The shell component can be used to print output of a complex unix expression. The output will be trimmed before inserting in the documentation. This can be disabled with the noTrim option.
<shell>
(echo abc; sleep 1; echo def; sleep 1; echo ghi) | node test/fixture/node
</shell>
| Result Embedded Into README |
|---|
|
<argufy>This component is used together with Argufy package which keeps arguments to command-line programs in an XML file, and allows to generate JS to extract them from process.argv easily and in Google Closure Compiler-compatible way. Documentary allows to place the table with all arguments defined in the arguments.xml file by using <argufy>types/arguments.xml</argufy> marker. It's child is the location of the arguments file, and if not given, it will default to types/arguments.xml. If an arg element had toc property, it will also be liked to the ToC using a toc-title. See the table generated for Documentary for an example of how the documentation of CLI arguments will look like.
<md2html>Converts the markdown with _/__/*/**/` into html. The main use of this widget is to be able to write tables with markdown and avoid having a whitespace at the bottom of the table row:
<table>
<tr><td>
`Hello World`: _notice_ the padding at the **bottom** of this row.
</td></tr>
<tr><td>
<md2html>
`Markdown 2 HTML`: _the text_ has been updated with the **md2html** component.
</md2html>
</td></tr>
</table>
|
|
Markdown 2 HTML: the text has been updated with the md2html component.
|
Since comments found in <!-- comment --> sections are not visible to users, they will be removed from the compiled output document.
When there this a need to present some data in a repeatable format, macros can be used. First, a macro needs to be defined with the MACRO rule, and then referenced by the USE-MACRO rule.
%MACRO example
<details>
<summary>$1</summary>
NPM: _[$1](https://nodejs.tools/$2)_
GitHub: _[$1](https://github.com/artdecocode/$2)_
</details>
%
%USE-MACRO example
<data>Documentary</data>
<data>documentary</data>
%
%USE-MACRO example
<data>Zoroaster</data>
<data>zoroaster</data>
%
<details>
<summary>Documentary</summary>
NPM: _[Documentary](https://nodejs.tools/documentary)_
GitHub: _[Documentary](https://github.com/artdecocode/documentary)_
</details>
<details>
<summary>Zoroaster</summary>
NPM: _[Zoroaster](https://nodejs.tools/zoroaster)_
GitHub: _[Zoroaster](https://github.com/artdecocode/zoroaster)_
</details>
The data will be substituted with into $N placeholders using the <data> elements found.
NPM: Documentary GitHub: Documentary
Currently, a macro can only be defined in the same file as its usage. Also, in future, macros will improve my allowing to use named placeholders.
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, such that the index.md of a directory will always go first, and the footer.md will go last. To print in reverse order, for example when writing a blog and name files by their dates, the --reverse flag can be passed to the CLI.
Example structure used in this documentation:
documentary
├── 1-installation-and-usage
│ └── index.md
├── 2-features
│ ├── 1-toc.md
│ ├── 1-toc2-section-breaks.md
│ ├── 10-type.md
│ ├── 2-tables.md
│ ├── 3-examples.md
│ ├── 3-fork.md
│ ├── 3-method-title.md
│ ├── 3.5-components
│ │ ├── 1-jsx-components.md
│ │ ├── 1.5async.md
│ │ ├── 2-web-components.html
│ │ ├── 3-components.md
│ │ └── footer.md
│ ├── 4-comment-stripping.md
│ ├── 4-macros.md
│ ├── 5-file-splitting.md
│ ├── 6-rules.md
│ ├── 8-gif.md
│ ├── 9-typal.md
│ └── footer.md
├── 3-cli.md
├── 4-api
│ ├── 1-toc.md
│ └── index.md
├── footer.md
└── index.md
There are some other built-in rules for replacements which are listed in this table.
| 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 given arguments. If tree is not installed, warns and does not replace the match. |
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>
Typal is a package to manage JSDoc typedefs from a separate types.xml file (or files). They can then be placed into JavaScript, used to generate Google Closure Compiler externs and embedded into documentation with Documentary. When placed in JS, one of the advantages is that it allows to expand function parameters' properties, so that they are better visible from the IDE:
The main use of Typal is together with Documentary to insert tables with types' descriptions.
To place a type definition as a table into a README file, the TYPEDEF marker 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.
<types>
<import name="ServerResponse" from="http"
link="https://nodejs.org/api/http.html#http_class_http_serverresponse"
/>
<type name="SetHeaders"
type="(res: ServerResponse) => any"
desc="Function to set custom headers on response." />
<type name="RightsConfig"
type="{ location: string, rights: number }[]"
desc="Configuration of read and write access rights." />
<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>
<prop opt type="Promise.<RightsConfig>" name="rightsPromise">
The promise which will be resolved with access rights to files.
</prop>
</type>
</types>
%TYPEDEF path/definitions.xml [TypeName]%
For example, using the 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:
%TYPEDEF types/static.xml%
and embed resulting type definitions (with the imported type linked to the Node.JS documentation due to its link attribute):
import('http').ServerResponse http.ServerResponse
(res: ServerResponse) => any SetHeaders: Function to set custom headers on response.
{ location: string, rights: number }[] RightsConfig: Configuration of read and write access rights.
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. | - |
| rightsPromise | Promise<RightsConfig> | The promise which will be resolved with access rights to files. | - |
Documentary wil scan each source file of the documentation first to build a map of all types. Whenever a property appears to be of a known type, it will be automatically linked to the location where it was defined. It is also true for properties described as generic types, such as Promise<Type>. This makes it possible to define all types in one place, and then reference them in the API documentation. For the full list of supported types for linking, see Typal's documentation.
Read More about types in Documentary including advanced usage with the spread option.
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). |
The program is used from the CLI (or package.json script).
doc [source] [-o output] [-trwcn] [-p "commit message"] [-h1] [-eg] [-vh]
The arguments it accepts are:
| Argument | Short | Description |
|---|---|---|
| source |
The documentary file or directory to process. Default documentary.
| |
| --output | -o |
Where to save the output (e.g., README.md).
If not passed, prints to stdout.
|
| --toc | -t | Just print the table of contents. |
| --reverse | -r | Print files in reverse order. Useful for blogs. |
| --h1 | -h1 |
Add h1 headings to the Table of Contents.
|
| --watch | -w | Watch files for changes and recompile the documentation. |
| --no-cache | -c |
Disable forks' cache for the run. The new output of
forks will be updated in cache so that it can be used
next time without -c arg.
|
| --namespace | -n | The root namespace: types within it will not be printed with their namespace prefix. |
| --push | -p | Starts Documentary in watch mode. After changes are detected, the commit is undone, and new one is made over it, forcing git push. |
| --generate | -g |
[Deprecated] Places typedefs definitions into JavaScript
files from types.xml. Use typal instead.
|
| --extract | -e |
[Deprecated] Migrates existing typedefs from a JavaScript
file into types.xml. Use typal -m instead.
|
| --version | -v | Prints the current version. |
| --help | -h | Shows the usage information. |
When NODE_DEBUG=doc is set, the program will print processing information, e.g.,
DOC 80734: stripping comment
DOC 80734: could not parse the table
The programmatic use of 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.
Section breaks from FoglihtenDeH0 font.
| © Art Deco 2019 |
| Tech Nation Visa Sucks |
|---|
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.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."