Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
documentary
Advanced tools
Documentation Compiler To Generate The Table Of Contents, Embed Examples With Their Output, Make Markdown Tables, Maintain Typedefs For JavaScript And README, Watch Changes To Push, Use Macros And Prettify API Titles.
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 |
WikiEach 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 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.
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. |
--readme | -m | Whether to output to README.md file.
Short for -o README.md . |
--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.
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 are ignored by default. This can be changed by setting the DOCUMENTARY_IGNORE_HIDDEN=false
env variable.
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.
Section breaks from FoglihtenDeH0 font.
© Art Deco™ 2020 |
---|
FAQs
Documentation Compiler To Generate The Table Of Contents, Embed Examples With Their Output, Make Markdown Tables, Maintain Typedefs For JavaScript And README, Watch Changes To Push, Use Macros And Prettify API Titles.
The npm package documentary receives a total of 49 weekly downloads. As such, documentary popularity was classified as not popular.
We found that documentary demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.