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
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 -->example/index.js<!-- Typedefs with linking -->types/index.xml<!-- Methods with custom heading designs -->```## runSoftware[["program", "string"],["config=", "Object"]]```<!-- Section Breaks -->%~ width="25"%<!-- JSX Components -->Checkout
All of these features come with just 3 transient dependencies in your
../documentary-test/node_modules├── alamode├── documentary├── preact└── typal
Table Of Contents
Each feature of Documentary is described on its relevant Wiki page.
Installation & Usage
doc client is available after installation. It can be used in a
doc script of
package.json, as follows:
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.,
Therefore, to produce an output
README.md, the following command will be used:
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.
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
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.
|%NPM: package-name%||Adds an NPM badge, e.g.,
|%TREE directory ...args%||Executes the
The program is used from the CLI (or
doc [source] [-o output] [-trwcn] [-p "commit message"] [-h1] [-eg] [-vh]
The arguments it accepts are:
|source||The documentary file or directory to process. Default
|--output||-o||Where to save the output (e.g.,
|--wiki||-W||Generate documentation in Wiki mode. The value of the argument must be the location of wiki, e.g.,
|--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.,
|--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.|
|--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
|--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.|
files from types.xml. Use
file into types.xml. Use
|--version||-v||Prints the current version.|
|--help||-h||Shows the usage information.|
NODE_DEBUG=doc is set, 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.
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.
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 2019||Tech Nation Visa Sucks|