barchart / documentation-generator Goto Github PK

View Code? Open in Web Editor NEW

Command-line tool for generating technical documentation sites

License: Other

JavaScript 76.40% CSS 0.24% Handlebars 23.36%

documentation-generator's Introduction

@barchart/documentation-generator

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