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 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 features. Documentary serves as a pre-processor of documentation and enhances every area of the task of making available high-quality docs for Node.JS (and other languages) packages for fellow developers.
yarn add -D documentary
npm i documentary --save-dev
For example, these are some pieces of documentation infrastructure made available by Documentary:
<!-- Tables Of Contents -->
%TOC%
<!-- Examples with paths renaming -->
%EXAMPLE: example/index.js, ../src => documentary%
<!-- Forks, native with import/export/jsx -->
<fork stderr nocache env="HELLO=WORLD">
example/index.js
</fork>
<!-- Typedefs with linking -->
<typedef narrow flatten>
types/index.xml
</typedef>
<!-- Methods with custom heading designs -->
```## runSoftware
[
["program", "string"],
["config=", "Object"]
]
```
<!-- Section Breaks -->
%~ width="25"%
<!-- JSX Components -->
<my-component package="documentary">
Checkout https://readme.page
</my-component>All of these features come with just 3 transient dependencies in your node_modules:
../documentary-test/node_modules
├── alamode
├── documentary
├── preact
└── typal
|
Each feature of Documentary is described on its relevant Wiki page.
|
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 docWhen 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.
These are some essential feature of Documentary.
Since comments found in <!-- comment --> sections are not visible to users, they will be removed from the compiled 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, 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
│ ├── 4-comment-stripping.md
│ ├── 5-file-splitting.md
│ ├── 6-rules.md
│ └── index.md
├── 3-cli.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 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. |
| --wiki | -W | Generate documentation in Wiki mode. The value of the argument must be the location of wiki, e.g., ../documentary.wiki. The --output option in this case has no effect. |
| --focus | -f | When generating Wiki, this is a list of comma-separated values that will be converted into RegEx'es used to specify which pages to process in current compilation, e.g., Address, Addr or Address,DNS. |
| --toc | -t | Just print the table of contents. |
| --types | -T | The location of types' files which are not referenced in the documentation (e.g., for printing links to external docs). |
| --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. |
| --debug | -d | Print verbose debug information.
Same as setting NODE_DEBUG=doc. |
| --annotate | -a | Place resolved URLs to all documented types into the
typedefs.json file and reference it in package.json. |
| --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 (or -d flag is passed), the program will print processing information, e.g.,
DOC 80734: stripping comment
DOC 80734: could not parse the table
This is quite essential to understanding the status of documentation processing, and will be enabled by default in the next version.
Only the following extensions are processed: markdown, md, html, htm. Anything else is ignored. This is to allow to place examples in the documentary folder. To process all files, set the ONLY_DOC=false variable.
Hidden Files
Hidden files are ignored by default. This can be changed by setting the DOCUMENTARY_IGNORE_HIDDEN=false env variable.
Titles 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.
- Online Documentation: documentation which is accessible online, such as on a GitHub website, or a language reference, e.g., Node.js Documentation.
- Editor Documentation: hints available to the users of an IDE, or an editor, in form of suggestions and descriptive hints on hover over variables' names.
Section breaks from FoglihtenDeH0 font.
|
© Art Deco™ 2020 |
|---|
