js-automatic-documentation

Overview

js-automatic-documentation is a tool designed to automatically generate documentation from the Abstract Syntax Tree (AST) of JavaScript and TypeScript projects. By using the TypeScript compiler and the ts-morph library, the tool extracts information about imports, exports, and code structure, producing documentation in HTML and Markdown.

The tool also uses JSDoc comments to fill the generated documentation with descriptions, parameters, and return types. This makes it useful for projects with incomplete or missing documentation, providing more precise way to document projects.

Features

• Extracted information:
  • Imports: Named, default, and namespace imports with their dependencies.
  • Exports: Functions, classes, constants, and additional information like parameters and return types.
• JSDoc parsing:
  • Uses the doctrine library to parse JSDoc comments and use them in the generated documentation.
• Multiple output formats:
  • Supports both HTML and Markdown templates using the mustache library.
• Static file hosting:
  • Serves generated HTML documentation locally with HTTP server using the serve library.
• CLI interface:
  • Supports CLI options for selecting the format, project initialization, and server hosting.
• Ease of use:
  • Available as an npx package.

Installation

You can use this tool with npx:

npx js-automatic-documentation [project-path] --format [html|md]

Usage

Generate documentation

Run the tool from your project directory to generate documentation:

npx js-automatic-documentation ./path/to/project --format html

Initialize TypeScript configuration

To set up a tsconfig.json file for the project, use the --init flag:

npx js-automatic-documentation ./path/to/project --init

Serve documentation locally

Serve the documentation locally by providing the --listen flag with a port number:

npx js-automatic-documentation ./path/to/project --format html --listen 8080

Visit http://localhost:8080 to view the documentation.

CLI options

| Option | Alias | Description | |-------------|-------|-----------------------------------| | --format | -f | Output format (html or md). | | --init | -i | Initialize a tsconfig.json file.| | --listen | -l | Serve HTML documentation on a port.|

How it works

1. AST parsing: The tool uses ts-morph to analyze the TypeScript AST and extract data about imports, exports, and code structure.
2. JSDoc integration: The doctrine library processes JSDoc comments for additional data like descriptions and parameter details.
3. Template rendering: Documentation is generated using mustache templates in HTML or Markdown format.
4. Static file hosting: An optional HTTP server hosts the generated HTML documentation.

Dependencies

| Dependency | Purpose | |---------------|----------------------------------------------| | ts-morph | Simplification of using TypeScript AST. | | doctrine | JSDoc parsing and data extraction. | | mustache | Template rendering for HTML/Markdown. | | serve | Hosting static HTML files locally. | | minimist | Parsing CLI flags. |

Run locally

Clone the project and install dependencies:

cd js-documentation
npm install
cd js-documentation/test
npm install

Generate documentation:

npx js-automatic-documentation ./test -l 8000