Documentation Generators

class MarkdownDocumenter {
  /**
   * Creates a new MarkdownDocumenter instance
   * @param options - Configuration options for the documenter
   */
  constructor(options: IMarkdownDocumenterOptions);
  
  /**
   * Generates all markdown documentation files
   */
  generateFiles(): void;
}

interface IMarkdownDocumenterOptions {
  /**
   * The API model containing the API items to document
   */
  apiModel: ApiModel;
  
  /**
   * Optional configuration for customizing output
   */
  documenterConfig: DocumenterConfig | undefined;
  
  /**
   * Output folder path where markdown files will be written
   */
  outputFolder: string;
}

import { ApiModel } from "@microsoft/api-extractor-model";
import { MarkdownDocumenter, IMarkdownDocumenterOptions } from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
import { DocumenterConfig } from "@microsoft/api-documenter/lib/documenters/DocumenterConfig";

// Load API model from API Extractor files
const apiModel = new ApiModel();
apiModel.loadPackage('./temp/my-package.api.json');

// Generate markdown documentation
const markdownDocumenter = new MarkdownDocumenter({
  apiModel,
  outputFolder: './docs'
});

markdownDocumenter.generateFiles();

class YamlDocumenter {
  /**
   * Creates a new YamlDocumenter instance
   * @param apiModel - The API model containing the API items to document
   * @param newDocfxNamespaces - Optional flag to enable new DocFX namespace support
   * @param yamlFormat - Optional YAML format ('udp' or 'sdp', defaults to 'sdp')
   */
  constructor(
    apiModel: ApiModel,
    newDocfxNamespaces?: boolean,
    yamlFormat?: YamlFormat
  );
  
  /**
   * Generates all YAML documentation files
   * @param outputFolder - Output folder path where YAML files will be written
   */
  generateFiles(outputFolder: string): void;
}

type YamlFormat = 'udp' | 'sdp';

class OfficeYamlDocumenter extends YamlDocumenter {
  /**
   * Creates a new OfficeYamlDocumenter instance
   * @param apiModel - The API model containing the API items to document
   * @param inputFolder - Input folder path containing snippets and other resources
   * @param newDocfxNamespaces - Optional flag to enable new DocFX namespace support
   */
  constructor(
    apiModel: ApiModel,
    inputFolder: string,
    newDocfxNamespaces?: boolean
  );
}

import { ApiModel } from "@microsoft/api-extractor-model";
import { OfficeYamlDocumenter } from "@microsoft/api-documenter/lib/documenters/OfficeYamlDocumenter";

const apiModel = new ApiModel();
apiModel.loadPackage('./temp/office-addin.api.json');

const yamlDocumenter = new OfficeYamlDocumenter(
  apiModel,
  './input', // folder containing snippets.yaml
  false // newDocfxNamespaces
);

yamlDocumenter.generateFiles('./yaml-docs');

class ExperimentalYamlDocumenter extends YamlDocumenter {
  /**
   * Creates a new ExperimentalYamlDocumenter instance
   * @param apiModel - The API model containing the API items to document
   * @param newDocfxNamespaces - Optional flag to enable new DocFX namespace support
   * @param yamlFormat - Optional YAML format ('udp' or 'sdp', defaults to 'sdp')
   */
  constructor(
    apiModel: ApiModel,
    newDocfxNamespaces?: boolean,
    yamlFormat?: YamlFormat
  );
}

class DocumenterConfig {
  /**
   * Loads configuration from api-documenter.json file
   * @param configFilePath - Path to the configuration file
   * @returns Loaded configuration object
   */
  static loadFile(configFilePath: string): DocumenterConfig;
  
  /**
   * Configuration settings loaded from file
   */
  readonly configFile: IConfigFile;
}

interface IConfigFile {
  /**
   * Configuration format version
   */
  configFormatVersion: string;
  
  /**
   * Output targets configuration
   */
  outputTargets?: IConfigOutputTarget[];
  
  /**
   * Newline character setting
   */
  newlineKind?: 'crlf' | 'lf';
  
  /**
   * Plugin configurations
   */
  plugins?: IConfigPlugin[];
  
  /**
   * Table of contents configuration
   */
  tableOfContents?: IConfigTableOfContents;
}

interface IConfigPlugin {
  /**
   * NPM package name of the plugin
   */
  packageName: string;
  
  /**
   * Whether the plugin is enabled
   */
  enabled: boolean;
  
  /**
   * Plugin-specific options
   */
  options?: Record<string, any>;
}

interface IConfigTableOfContents {
  /**
   * Category name for uncategorized API items
   */
  catchAllCategory?: string;
}

import { DocumenterConfig, IConfigFile, IConfigPlugin, IConfigTableOfContents } from "@microsoft/api-documenter/lib/documenters/DocumenterConfig";

// Load configuration from file
const config = DocumenterConfig.loadFile('./api-documenter.json');

// Use config with documenter
const markdownDocumenter = new MarkdownDocumenter({
  apiModel,
  documenterConfig: config,
  outputFolder: './docs'
});

import { ApiModel } from "@microsoft/api-extractor-model";
import { 
  MarkdownDocumenter,
  CustomMarkdownEmitter 
} from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
import { 
  CustomDocNodes 
} from "@microsoft/api-documenter/lib/nodes/CustomDocNodes";
import { DocHeading } from "@microsoft/api-documenter/lib/nodes/DocHeading";

// Create custom markdown emitter with enhanced formatting
class EnhancedMarkdownEmitter extends CustomMarkdownEmitter {
  protected writeHeading(docHeading: DocHeading): void {
    // Custom heading formatting
    const level = Math.min(docHeading.level, 6);
    this.writeNewline();
    this.writePlainText('#'.repeat(level) + ' ' + docHeading.title);
    this.writeNewline();
  }
}

// Use custom emitter with documenter
const apiModel = new ApiModel();
const documenter = new MarkdownDocumenter({
  apiModel,
  outputFolder: './docs'
});

import { ApiModel } from "@microsoft/api-extractor-model";
import { MarkdownDocumenter, IMarkdownDocumenterOptions } from "@microsoft/api-documenter/lib/documenters/MarkdownDocumenter";
import * as path from "path";

// Process multiple API packages
const packages = [
  './temp/package-a.api.json',
  './temp/package-b.api.json',
  './temp/package-c.api.json'
];

const apiModel = new ApiModel();

// Load all packages into single model
for (const packagePath of packages) {
  apiModel.loadPackage(packagePath);
}

// Generate combined documentation
const documenter = new MarkdownDocumenter({
  apiModel,
  outputFolder: './combined-docs'
});

documenter.generateFiles();

import { YamlFormat } from "@microsoft/api-documenter/lib/documenters/YamlDocumenter";

// Available YAML formats
type YamlFormat = 'udp' | 'sdp';

// UDP format: Legacy Universal DocFX Platform format
// SDP format: Structured Data Platform format (default, recommended)

class IndentedWriter {
  /**
   * Creates a new IndentedWriter instance
   * @param builder - StringBuilder to write to
   * @param defaultIndentPrefix - Default indentation string (default: two spaces)
   */
  constructor(builder: StringBuilder, defaultIndentPrefix?: string);
  
  /**
   * Writes text without indentation
   * @param text - Text to write
   */
  write(text: string): void;
  
  /**
   * Writes text with current indentation
   * @param text - Text to write
   */
  writeLine(text?: string): void;
  
  /**
   * Increases indentation level
   */
  increaseIndent(): void;
  
  /**
   * Decreases indentation level
   */
  decreaseIndent(): void;
}

class Utilities {
  /**
   * Generates a safe filename from an API item display name
   * @param name - The display name to convert
   * @returns Safe filename string
   */
  static getSafeFilenameForName(name: string): string;
  
  /**
   * Concatenates signature parts into a readable format
   * @param parts - Array of signature parts
   * @returns Formatted signature string
   */
  static getConciseSignature(parts: string[]): string;
}