documentary

Documentary

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

Table Of Contents Table Of Contents Wiki Installation & Usage Misc Comments Stripping File Splitting Replacement Rules CLI NODE_DEBUG=doc Markdown Files Hidden Files ♫ PRO ♪ Underlined ♯ Titles Glossary Online Documentation Editor Documentation Copyright

Wiki Each feature of Documentary is described on its relevant Wiki page. ⭐️Key Features: A quick overview of the solutions provided by Documentary for developers to make writing documentation a breeze. 📖Tables Of Content: Creating a navigation menu for the README page. ⚜️Section Breaks: Placing visual separators of sections. 📐JSON Tables: Writing JSON array data to be converted into a Markdown table. 📜Embed Examples: Decoupling examples from documentation by maintaining separate runnable example file. 🍴Forks (Embed Output): Executing examples to show their output, and validating that program works correctly. 🎩Method Titles: Documenting methods in a standard way, and provide your own designs. 🎇JSX Components: Implementing custom system-wide and project-scoped components. 🤖Macros: Constructing patterns to be reused in formation of READMEs. ☀️Typedefs: Display @typedef information in README files by maintaining types externally to JS source. 🎼Type (Deprecated): An older version of typedefs which works as a macro for types. 🥠Gif Detail: Hiding images inside of the <details> block. 🖱API: Using Documentary's features from other packages.

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

Misc

These are some essential feature of Documentary.

Comments Stripping

Since comments found in <!-- comment --> sections are not visible to users, they will be removed from the compiled output document.

File Splitting

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

Replacement Rules

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.

CLI

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.
--gitlab		Used when generating documentation for GitLab. Currently only has affect on images in wikis.
--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.

Markdown Files

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.

♫ PRO ♪ Underlined ♯ Titles

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.

Glossary

• 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.

Copyright

Section breaks from FoglihtenDeH0 font.

	© Art Deco™ 2020