Skip to content

Command-line tool for generating technical documentation sites

License

Notifications You must be signed in to change notification settings

barchart/documentation-generator

Repository files navigation

@barchart/documentation-generator

AWS CodeBuild NPM

A command-line tool that quickly generates easy-to-maintain websites for technical documentation adhering to Barchart's guidelines for content, style, and layout.

Basic Features

  • Emits a single-page web application using Docsify, with:
    • a standard cover page,
    • a standard sidebar,
    • a standard page structure, and
    • a standard stylesheet.
  • Creates skeleton of pages, with:
    • placeholder pages (written using Markdown).
  • Auto-generates SDK documentation from your code, as follows:
    • parses your JavaScript files,
    • extracts JSDoc comments, and
    • emits markdown pages.
  • Auto-generates API documentation for your web service, as follows:
    • parses your OpenAPI file (or URL), and
    • emits markdown pages.
  • Easy to deploy and maintain using GitHub Pages.

Example Sites

These Barchart products were documented using this tool; the sites are hosted on GitHub Pages:

Usage Guide

This tool was used to document itself (see the docs folder). The resulting site has been published here:

https://barchart.github.io/documentation-generator/#/

If you're pathologically incapable of reading documentation — which would be ironic, considering the purpose of this tool — just execute the following shell commands:

npm install -g @barchart/documentation-generator

mkdir my-first-documentation-site
cd my-first-documentation-site

documentation init
documentation serve

Compatibility

This tool should be compatible with Node.js version 20.

Package Managers

This tool is a public package on NPM, named @barchart/documentation-generator.

License

This software is provided under the MIT license.