Skip to main content

​
Overview

The CLI layer is the entry point for mint-tsdocs, responsible for parsing user commands and initiating the documentation generation process. Built on @rushstack/ts-command-line, it provides a robust, typed command-line interface.
Entry Point: src/start.ts creates the CLI instance and runs the parser

​
Component Architecture

  • start.ts
  • ApiDocumenterCommandLine
  • BaseAction
  • MarkdownAction
The Executable Entry Point
src/start.ts
import { DocumenterCli } from './cli/ApiDocumenterCommandLine';

const parser: DocumenterCli = new DocumenterCli();
parser.executeAsync().catch(console.error);
Responsibilities:
  • Display version banner
  • Create CLI parser instance
  • Execute command and handle errors

​
Execution Flow

​
Detailed Flow Breakdown

User runs the command:
mint-tsdocs markdown -i ./temp -o ./docs/api --docs-json ./docs/docs.json
  • Binary executes lib/start.js
  • Version banner is displayed
  • DocumenterCli instance is created
DocumenterCli.executeAsync() processes the command:
  • Identifies action: markdown
  • Validates required parameters
  • Parses all flags and values
  • Routes to MarkdownAction.onExecuteAsync()
BaseAction.buildApiModel() loads the API data:
const apiModel: ApiModel = new ApiModel();
const inputFolder = this._inputFolderParameter.value || './input';

// Find and load all *.api.json files
for (const filename of FileSystem.readFolderItemNames(inputFolder)) {
  if (filename.match(/\.api\.json$/i)) {
    apiModel.loadPackage(path.join(inputFolder, filename));
  }
}

// Apply @inheritDoc workarounds
this._applyInheritDoc(apiModel, apiModel);

return { apiModel, inputFolder, outputFolder };
MarkdownAction creates and configures the documenter:
const markdownDocumenter = new MarkdownDocumenter({
  apiModel,
  outputFolder,
  docsJsonPath: this._docsJsonParameter.value,
  tabName: this._tabNameParameter.value,
  groupName: this._groupParameter.value,
  enableMenu: this._menuParameter.value,
  convertReadme: this._readmeParameter.value,
  readmeTitle: this._readmeTitleParameter.value || 'README'
});
Control passes to the generation layer:
markdownDocumenter.generateFiles();
The CLI layer’s work is complete - the generation layer takes over.

​
Parameter Validation

The CLI layer ensures all parameters are valid before proceeding: 
const inputFolder = this._inputFolderParameter.value || './input';
if (!FileSystem.exists(inputFolder)) {
  throw new Error('The input folder does not exist: ' + inputFolder);
}

​
Error Handling

The CLI layer provides early validation to fail fast with clear error messages
Common errors caught at the CLI layer:
ErrorCauseSolution
Input folder not foundInvalid -i pathVerify path exists
No .api.json filesWrong input folderRun api-extractor first
Invalid docs.jsonMalformed JSONValidate JSON syntax
Permission deniedOutput folder protectedCheck file permissions

​
Extending the CLI

​
Adding a New Parameter

1

Define in Action

this._myParameter = this.defineStringParameter({
  parameterLongName: '--my-option',
  argumentName: 'VALUE',
  description: 'My new option'
});
2

Pass to Documenter

const markdownDocumenter = new MarkdownDocumenter({
  // ... existing options
  myOption: this._myParameter.value
});
3

Update Interface

export interface IMarkdownDocumenterOptions {
  // ... existing properties
  myOption?: string;
}
4

Use in Generation

Use the new option in MarkdownDocumenter logic

​
Adding a New Command

To add a new command (e.g., yaml):
  1. Create YamlAction.ts extending BaseAction
  2. Implement onExecuteAsync()
  3. Register in ApiDocumenterCommandLine._populateActions()
private _populateActions(): void {
  this.addAction(new MarkdownAction(this));
  this.addAction(new YamlAction(this));  // New command
}

Generation Layer

See how the CLI hands off to the generation layer

Architecture Overview

Understand the full pipeline