@microsoft/api-documenter

What is @microsoft/api-documenter?

@microsoft/api-documenter is a tool for generating API documentation from TypeScript and JavaScript projects. It is part of the Rush Stack family of tools and is designed to work seamlessly with API Extractor to produce high-quality documentation in various formats.

What are @microsoft/api-documenter's main functionalities?

Generate Markdown Documentation

This command generates Markdown documentation from the API JSON files produced by API Extractor. The input folder should contain the API JSON files, and the output folder will contain the generated Markdown files.

npx api-documenter markdown -i <input-folder> -o <output-folder>

Generate YAML Documentation

This command generates YAML documentation from the API JSON files. The YAML format is often used for further processing or integration with other documentation systems.

npx api-documenter yaml -i <input-folder> -o <output-folder>

Customizing Output

You can customize the output of the documentation by providing a configuration file. This allows you to tailor the generated documentation to meet specific needs or standards.

npx api-documenter markdown -i <input-folder> -o <output-folder> --config <config-file>

Other packages similar to @microsoft/api-documenter

typedoc

TypeDoc is a documentation generator for TypeScript projects. It generates documentation directly from the source code and supports various output formats, including HTML and Markdown. Compared to @microsoft/api-documenter, TypeDoc is more focused on generating documentation directly from TypeScript source files rather than from API JSON files.

jsdoc

JSDoc is a popular tool for generating documentation from JavaScript code. It uses specially formatted comments within the source code to produce HTML documentation. JSDoc is more general-purpose and widely used in the JavaScript community, whereas @microsoft/api-documenter is more specialized for use with API Extractor and TypeScript projects.

documentation

The 'documentation' package is a documentation generator for JavaScript projects. It supports various output formats, including HTML, Markdown, and JSON. It is similar to JSDoc but offers more modern features and better support for ES6 and beyond. Compared to @microsoft/api-documenter, it is more focused on JavaScript and less integrated with TypeScript-specific tools.

README

@microsoft/api-documenter

This tool can be used to generate an online API reference manual for your TypeScript library. It reads the *.api.json data files produced by API Extractor, and then generates web pages using the Markdown file format.

The api-documenter tool is part of Microsoft's production documentation pipeline. It is provided as a code sample to illustrate how to load and process the API JSON file format. If your requirements are simple, you can use this tool directly. For more advanced scenarios, developers are encouraged to fork the project and modify the source code. The implementation is intentionally kept simple and easy to understand. This is possible because most of processing is already performed upstream by API Extractor.

For more information, see the Rendering API docs wiki article.