Usage

If you have already set up api-extractor and api-documenter, skip to the Generate AsciiDoc files section.

Before continuing, make sure you understand the API design constraints and known issues.

Install dependencies

First, install these dependencies:

$ yarn add --dev \
   @microsoft/api-extractor \
   @microsoft/api-documenter \
   api-documenter-yaml-to-antora-asciidoc

Set up api-extractor

api-extractor.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts", (1)
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/tmp/api/<unscopedPackageName>.api.json"
  },
  "apiReport": {
    "enabled": false, (2)
    "reportFolder": "<projectFolder>/api",
    "reportTempFolder": "<projectFolder>/tmp/api"
  },
  "dtsRollup": {
    "enabled": false, (3)
    "untrimmedFilePath": "",
    "publicTrimmedFilePath": "<projectFolder>/api/<unscopedPackageName>.d.ts"
  }
}

1	Change this to the path of your main entry point file.
2	If you want to generate an API report, set this to true.
3	If you want to generate a .d.ts rollup file, set this to true.

.gitignore

/api/
/tmp/
tsdoc-metadata.json

tsconfig.json

{
  "compilerOptions": {
    "declarationMap": true (1)
  }
}

1	Add this line.

Generate doc model files

$ yarn api-extractor run

Generate YAML files

$ yarn api-documenter yaml -i tmp/api -o tmp/api-yaml

Generate AsciiDoc files

Assuming that you have already generated the YAML files using api-documenter yaml command… To generate generate the AsciiDoc files, run the following command where <input-dir> is the directory that contains the .yml files:

$ yarn api-documenter-yaml-to-antora-asciidoc asciidoc -i tmp/api-yaml

This will generate the AsciiDoc pages in docs/modules/api/pages.

Set up navigation

It will also generate a navigation file at docs/modules/api/nav.adoc file that lists the pages in the documentation. You can then add this navigation file to your Antora project:

nav:
  - modules/api/nav.adoc (1)

1	Add this line.

Set up package.json

To generate the documentation easily, you can add the following to your package.json:

{
  "scripts": {
    "api": "api-extractor run && api-documenter yaml -i tmp/api -o tmp/api-yaml && api-documenter-yaml-to-antora-asciidoc asciidoc -i tmp/api-yaml" (1)
  }
}

1	Add this line.

Now, you can run yarn api to regenerate the documentation.

Use GitHub Actions to keep the documentation up-to-date

You can use GitHub Actions to automatically regenerate the documentation files when you push to the repository.

name: Update API documentation
on:
  workflow_dispatch:
  push:
jobs:
  build:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 16.x
      - name: Install dependencies
        run: yarn
      - name: Update API
        run: yarn api
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Update generated files as of ${{ github.sha }}
          file_pattern: api docs