https://github.com/artdecocode/documentary
A Node.js documentation pre-processor to increase productivity.
https://github.com/artdecocode/documentary
docs documentation markdown node nodejs npm readme
Last synced: about 1 year ago
JSON representation
A Node.js documentation pre-processor to increase productivity.
- Host: GitHub
- URL: https://github.com/artdecocode/documentary
- Owner: artdecocode
- License: mit
- Created: 2018-06-12T02:34:11.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-02-26T19:11:21.000Z (over 6 years ago)
- Last Synced: 2025-04-03T22:41:33.420Z (about 1 year ago)
- Topics: docs, documentation, markdown, node, nodejs, npm, readme
- Language: JavaScript
- Homepage: https://readme.page
- Size: 3.01 MB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Documentary
===
[](https://www.npmjs.com/package/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.
```sh
yarn add -D documentary
npm i documentary --save-dev
```
For example, these are some pieces of documentation infrastructure made available by _Documentary_:
````html
%TOC%
%EXAMPLE: example/index.js, ../src => documentary%
example/index.js
types/index.xml
```## runSoftware
[
["program", "string"],
["config=", "Object"]
]
```
%~ width="25"%
Checkout https://readme.page
````
All of these features come with just 3 transient dependencies in your `node_modules`:
```m
../documentary-test/node_modules
├── alamode
├── documentary
├── preact
└── typal
```
## Table Of Contents
- [Table Of Contents](#table-of-contents)
- [Wiki](#wiki)
- [Installation & Usage](#installation--usage)
- [Misc](#misc)
* [Comments Stripping](#comments-stripping)
* [File Splitting](#file-splitting)
* [Replacement Rules](#replacement-rules)
- [CLI](#cli)
* [`NODE_DEBUG=doc`](#node_debugdoc)
* [Markdown Files](#markdown-files)
* [Hidden Files](#hidden-files)
- [♫ PRO
♪ Underlined
♯ `Titles`](#-pro-underlined-titles)
- [Glossary](#glossary)
* [Online Documentation](#online-documentation)
* [Editor Documentation](#editor-documentation)
- [Copyright](#copyright)
## Wiki
Each feature of _Documentary_ is described on its relevant Wiki page.
- ⭐️[Key Features](../../wiki/Key-Features): A quick overview of the solutions provided by _Documentary_ for developers to make writing documentation a breeze.
- 📖[Tables Of Content](../../wiki/Tables-Of-Contents): Creating a navigation menu for the README page.
- ⚜️[Section Breaks](../../wiki/Section-Breaks): Placing visual separators of sections.
- 📐[JSON Tables](../../wiki/JSON-Tables): Writing _JSON_ array data to be converted into a Markdown table.
- 📜[Embed Examples](../../wiki/Embed-Examples): Decoupling examples from documentation by maintaining separate runnable example file.
- 🍴[Forks (Embed Output)](../../wiki/Forks): Executing examples to show their output, and validating that program works correctly.
- 🎩[Method Titles](../../wiki/Method-Titles): Documenting methods in a standard way, and provide your own designs.
- 🎇[JSX Components](../../wiki/JSX-Components): Implementing custom system-wide and project-scoped components.
- 🤖[Macros](../../wiki/Macros): Constructing patterns to be reused in formation of READMEs.
- ☀️[Typedefs](../../wiki/Typedefs): Display `@typedef` information in _README_ files by maintaining types externally to _JS_ source.
- 🎼[Type (Deprecated)](../../wiki/Type-(Deprecated)): An older version of typedefs which works as a macro for types.
- 🥠[Gif Detail](../../wiki/Gif-Detail): Hiding images inside of the `` block.
- 🖱[API](../../wiki/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:
```json
{
"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:
```sh
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 `` 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](#reverse-order) can be passed to the CLI.
Example structure used in this documentation:
```m
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).
```sh
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.
### 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.
```markdown
♫PRO
♪Underlined
♯ `Titles`
---
```
As seen in the [_Markdown Cheatsheet_](https://github.com/adam-p/markdown-here/wiki/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](https://nodejs.org/api/stream.html).
- **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](https://www.1001fonts.com/foglihtendeh0-font.html) font.
© Art Deco™ 2020
