docs-docgen-cli
v1.0.13
Published
CLI tool to generate a start-up set of files and folders for company products documentation hosted on a Docusaurus-powered site.
Downloads
750
Maintainers
Readme
CLI tool generating documentation files and folders for multiple projects on a Docusaurus-powered site.
Installation
Install the package locally using the global switch.
npm install docs-docgen-cli -g
After installing it locally, you can use from any folder on your computer. Check docs-docgen-cli
is available:
docs-docgen-cli -V
# output
# 1.0.3
Alternativelly, run docs-docgen-cli
without installing it locally (recommended).
npx docs-docgen-cli -V
Commands
build
- build files and folders for company product documentation structure for a Docusaurus-powered site.check
- check valid structure of product list files.help
- provide help text for a command.
Options
-h, --help
- provide application help.-V, --version
-- provide current application version.
build
command
This is the default command, i.e. this is the command executed when no command appears on the command line.
- Retrieves product list files using patterns in the arguments or default patterns.
- Collect product definitions from each product list file.
- For each product defined, generate a product folder under
docs
and anindex.md
file inside each product folder. - In the
docs
folder, generateindex.md
containing a list of products and links to product index page. - Generate an
.outline.yaml
that you will use withSkelo CLI
to complete the documentation start-up.
Usage
docs-docgen-cli [build] [patterns...] [options]
Arguments
[patterns...]
- optional list of product list filename patterns
Options
-d, --docs <path>
- path to Docusaurus docs folder. (default:website/docs
)-o, --outline <filename>
- name of the outline file intended for Skelo CLI (default:website/products.outline.yaml
)-v, --verbose
- verbose output--schema <filename>
- name of.json
file with product list definition schema (default:schema.json
)
If no patterns appear, the default pattern is used: **/*.[Pp]roducts.json
. If no files match this pattern, then the alternative pattern is used: __products__/**/*.json
Examples
docs-docgen-cli
- look for product files in current folder and matching the
**/*.[Pp]roducts.json
pattern. If no files match this pattern, look for files matching the__products__/**/*.json
(i.e. look for all files ending with.json
starting with the__products__
subfolder). -d
value:website/docs
-o
value:website/products.outline.yaml
website/products.outline.yaml
file:
sidebars:
- label: "product-one-sidebar"
items:
- label: "Product One documentation"
title: "Welcome to Product One documentation"
slug: "product-one-documentation"
brief: "Develop documentation with additional topics and categories in the `products.outline.yaml` in the `product-one-sidebar` sidebar definition"
docs-docgen-cli myproducts.products.json -v
- look for
myproducts.products.json
product list file in current folder. -d
value:website/docs
-o
value:website/products.outline.yaml
Product list schema
Product definitions appear in product list files. Product list files are .json
file containing an array of product definition items. To ensure product list files meet design specifications, a schema.json
file contains the validation schema.
A product definition item is either a string or an object. The following product list contains two product definition items:
[
" Product One ",
{
"label": " Product Two "
}
]
- A string product item may have heading or trailing spaces, and contain letters, digits, and spaces. Only a space is allowed between sequences of letters or digits.
- The object must have the
label
property, whose value is a string. The string forlabel
must adhere to the same rules as the string item. - Additional object properties include:
productId
- product slug stringpath
- path of folders preceding product documentation folder
The product list file schema is found in schema.json
in the application root folder.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"label": {
"type": "string",
"pattern": "^\\s*([a-zA-Z0-9]+\\s)*[a-zA-Z0-9]+\\s*$"
},
"productId": {
"type": "string",
"pattern": "^[a-z]+([-]?[a-z0-9]+)*$"
},
"path": {
"type": "string",
"pattern": "^([a-z]+([-]?[a-z0-9]+)*\\/)*[a-z]+([-]?[a-z0-9]+)*$"
},
"description": {
"type": "string"
}
},
"required": [
"label"
],
"additionalProperties": true
}
]
}
}
Property | Description | Default | Example |
:--|:--|:--|:--|
label
| Human readable product label identifying the product | | "Product One"
|
productId
| product slug string | slug of label
value | product-one
|
path
| | "" | "path/to/parent/to/product/folder"
|
Product list file examples
Defines two products, "Product One" and "Product Two" using strings.
[ "Product One", "Product Two" ]
The equivalent of object definition:
[ { "label": "Product One", "productId": "product-one" }, { "label": "Product Two", "productId": "product-two" } ]
Defines three product, two in string format and the third in object format:
[ "Product One", { "label": "Product Three" }, "Product Two" ]
The equivalent of object definition:
[ { "label": "Product One", "productId": "product-one" }, { "label": "Product Three", "productId": "product-three" }, { "label": "Product Two", "productId": "product-two" } ]
Defines four products, two in string format the third and fourth in object format. The fourth product has a specified
productId
value[ "Product One", { "label": "Product Three" }, "Product Two", { "label": "Product Four", "productId": "pr-4" } ]
The equivalent of object definition:
[ { "label": "Product One", "productId": "product-one" }, { "label": "Product Three", "productId": "product-three" }, { "label": "Product Two", "productId": "product-two" }, { "label": "Product Four", "productId": "pr-4" } ]
check
command
Validates product list files against the product list validation schema.
Usage
docs-docgen-cli check [patterns...] [options]
Arguments
[patterns...]
- optional list of product list filename patterns
Options
-v, --verbose
- verbose output--schema <filename>
- path to validation schema file (default:schema.json
)
Quick demo
For a quick demo of how to use docgen CLI
, visit Quick demo