api-documenter-yaml-to-antora-asciidoc

Finally, I found it. A documentation pipeline to generate API documentation for my TypeScript projects that works for me.

A diagram showing how the workflow works
Figure 1. The documentation pipeline

Example of generated documentation

My projects:

Demo:

Screenshots

Example 1
Example 2
Example 3

The documentation pipeline

Step Tool Description

1

TypeScript Compiler

Generates TypeScript declaration (.d.ts) files.

2

@microsoft/api-extractor

Generates “doc model” (.api.json) files (among other features).

  • The doc model describes the API surface of a TypeScript package.

  • It also validates the JSDoc comments and provides useful suggestions.

  • Maintained by Microsoft as part of the Rush Stack.

3

@microsoft/api-documenter

Generates SDP YAML (.yml) files.

  • SDP stands for Schema-driven Document Processor, a documentation YAML format for use in Microsoft’s documentation pipeline.

    • It can also be used with the DocFX v3.

    • Unfortunately not much documentation is available for this format, but there is a TypeScript definition file and the examples are easy to parse.

    • It specifies the structure of the documentation — each metadata file would correspond to a page in the generated documentation.

  • Maintained by Microsoft as part of the Rush Stack.

4

api-documenter-yaml-to-antora-asciidoc (this project!)

Generates AsciiDoc (.adoc) files.

  • It follows Antora’s folder and file structures, so that it can be easily used with Antora.

5

Antora

Generates a documentation site.

  • It is a multi-repository documentation generator — it can be used to generate a single documentation site for multiple projects.