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:

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.