Welcome to Kampose

Kampose /kam-pohz/ is a cross-platform command-line documentation composer for .NET projects. It combines assembly metadata, XML documentation comments, and conceptual topics, then renders them through configurable Handlebars themes.

Overview

Kampose generates API reference for libraries, frameworks, and internal APIs. It can also combine that reference with guides and tutorials, or build a topic-only documentation site without assemblies.

Auditing can report missing or incomplete XML documentation and verify referenced URLs. Configuration controls which checks run and whether reported issues stop the build.

Key Capabilities

• Multiple Output Formats - Generate HTML for websites or Markdown for wikis (GitHub, Azure DevOps)
• Flexible Configuration - JSON-based configuration with glob patterns for precise control over content discovery and organization
• Extensible Themes - Built-in themes with comprehensive customization options and support for custom theme development
• Content Integration - Combine API documentation with topics, tutorials, and guides, or generate topic-only documentation sites
• Quality Assurance - Built-in auditing validates documentation completeness and enforces quality standards
• CI/CD Integration - Designed for automated generation in GitHub Actions, Azure Pipelines, and other CI/CD platforms

Getting Started

Installation

Install Kampose as a .NET Global Tool:

dotnet tool install --global kampose

To update to the latest version, run:

dotnet tool update --global kampose

Basic Usage

Follow these simple steps to generate your first API documentation with Kampose.

Step 1: Enable XML documentation generation in your project file:

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Step 2: Create a configuration file (kampose.json) in your project root:

{
    "$schema": "https://kampute.github.io/kampose/json-schemas/configuration.schema.json",
    "convention": "dotNet",
    "outputDirectory": "docs",
    "assemblies": ["bin/Release/**/*.dll"],
    "theme": "classic"
}

For more configuration options and examples, refer to the Configuration guide.

Step 3: Build your project and generate documentation:

dotnet build -c Release
kampose build

For detailed usage instructions and examples, see the Command-Line Interface guide.

Guide to This Documentation

This guide organizes Kampose's documentation into key areas to help you navigate and find the information you need efficiently.

Commands and Configuration

• Command-Line Interface - Commands, options, and usage patterns
• Configuration Guide - Complete configuration reference with examples
• Glob Patterns - File selection patterns for assemblies, XML docs, and topics

Integration and Automation

• CI/CD Integration - Automate documentation generation in GitHub Actions, Azure Pipelines, and GitLab CI/CD

Writing Documentation

• Writing Documentation - Choose and author conceptual or API documentation
• URL Resolution - Choose document-, site-, or documentation-root-relative URLs

Customizing Output

• Themes Overview - Available themes and configuration
• Classic HTML Theme - HTML theme customization
• Classic Markdown Theme - Markdown theme and DevOps wiki integration
• Theme Authoring Guide - Creating custom themes

Support and Community

Kampose is an open-source project released under the MIT License. Contributions, bug reports, and feature requests are welcome.

Acknowledgments

Kampose is built on outstanding open-source projects maintained by the .NET and broader development community:

• Handlebars.Net - Powerful template engine enabling flexible theme development
• JsonSchema.Net - Robust JSON schema validation for configuration files
• Markdig - Fast and extensible Markdown processing
• Microsoft.Extensions.FileSystemGlobbing - Flexible file pattern matching for assembly and content discovery
• NUglify - Asset minification and optimization
• PrismJS - Syntax highlighting for code samples in documentation

The dedication and expertise of these project maintainers and contributors make Kampose possible. Thank you to everyone who contributes to the open-source ecosystem.