CI/CD Integration

Kampose integrates seamlessly into automated build and deployment pipelines, enabling documentation generation as part of your continuous integration workflow. This guide provides examples for popular CI/CD platforms.

Project Assumptions

The examples in this guide assume a standard .NET project structure:

Solution file in the repository root
Project source code in src/ directory
Build output in bin/Release/ directories
XML documentation files generated alongside assemblies

Configuration File

All examples use this kampose.json configuration file in the repository root:

{
  "convention": "dotNet",
  "outputDirectory": ".doc-site",
  "assemblies": ["src/**/bin/Release/**/*.dll"],
  "theme": "classic",
  "audit": {
    "options": ["recommended"],
    "stopOnIssues": true
  }
}

This configuration:

Uses the dotNet convention for .NET-style documentation structure
Outputs generated documentation to the .doc-site directory
Collects all assemblies and XML documentation files from Release build outputs
Uses the classic theme for documentation styling
Enables recommended audit options with quality gates (stopOnIssues: true) to fail builds if documentation issues are detected

.NET SDK Requirements

Kampose is built with .NET 10.0 and requires the .NET 10.0 SDK to be installed. The workflow examples install .NET 10.0 for this purpose. If your project targets a different .NET version (e.g., .NET 8.0), you can install multiple SDK versions in the same pipeline.

Version Pinning

The workflow examples in this guide install the latest version of Kampose:

dotnet tool install --global kampose

While this is convenient for getting started, it's recommended to pin to a specific version in production pipelines:

dotnet tool install --global kampose --version 0.2.0

Pinning to a specific version prevents builds from failing unexpectedly if a newer version introduces breaking changes. When you're ready to upgrade, you can test the new version in a separate branch before updating your main pipeline.

GitHub Actions

Basic Workflow

Generate documentation on each push to the main branch and deploy to GitHub Pages:

name: build

on:
  workflow_dispatch:  # Allow manual trigger
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-test-document:
    runs-on: ubuntu-latest

    permissions:
      contents: write  # Required for GitHub Pages deployment

    steps:
    - uses: actions/checkout@v4

    - name: Setup .NET SDK
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '10.0.x'

    - name: Restore Dependencies
      run: dotnet restore

    - name: Build Solution
      run: dotnet build --no-restore -c Release

    - name: Test Solution
      run: dotnet test --no-restore --no-build -c Release --verbosity minimal

    - name: Install Kampose for Documentation Generation
      run: dotnet tool install --global kampose

    - name: Generate Documentation
      run: kampose build

    # Only deploy to GitHub Pages on main branch (not on PRs)
    - name: Deploy Documentation to GitHub Pages
      if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
      uses: peaceiris/actions-gh-pages@v4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./.doc-site
        keep_files: false

Azure Pipelines

Basic Pipeline

Generate documentation on each push to the main branch and publish as a build artifact:

# Trigger on pushes to main branch
trigger:
  branches:
    include:
      - main

# Trigger on pull requests to main branch
pr:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: UseDotNet@2
    displayName: 'Install .NET SDK'
    inputs:
      version: '10.0.x'

  - script: dotnet restore
    displayName: 'Restore Dependencies'

  - script: dotnet build --no-restore -c Release
    displayName: 'Build Solution'

  - script: dotnet test --no-restore --no-build -c Release --verbosity minimal
    displayName: 'Test Solution'

  - script: dotnet tool install --global kampose
    displayName: 'Install Kampose for Documentation Generation'

  - script: kampose build
    displayName: 'Generate Documentation'

  # Only publish artifact on main branch (not on PRs)
  - task: PublishBuildArtifacts@1
    displayName: 'Publish Documentation Artifact'
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
    inputs:
      pathToPublish: '.doc-site'
      artifactName: 'documentation'

Pipeline with Wiki Publishing

Publish documentation directly to Azure DevOps Wiki. Update your kampose.json to use the devOps convention and wiki-compatible output directory:

{
  "convention": "devOps",
  "outputDirectory": ".doc-site",
  "assemblies": ["src/**/bin/Release/**/*.dll"],
  "theme": "classic",
  "audit": {
    "options": ["recommended"],
    "stopOnIssues": true
  }
}

The devOps convention generates documentation optimized for Azure DevOps Wiki integration. See the Configuration Guide for more details about conventions.

# Trigger on pushes to main branch
trigger:
  branches:
    include:
      - main

# Trigger on pull requests to main branch
pr:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: UseDotNet@2
    displayName: 'Install .NET SDK'
    inputs:
      version: '10.0.x'

  - script: dotnet restore
    displayName: 'Restore Dependencies'

  - script: dotnet build --no-restore -c Release
    displayName: 'Build Solution'

  - script: dotnet test --no-restore --no-build -c Release --verbosity minimal
    displayName: 'Test Solution'

  - script: dotnet tool install --global kampose
    displayName: 'Install Kampose for Documentation Generation'

  - script: kampose build
    displayName: 'Generate Documentation'

  # Only publish to wiki on main branch (not on PRs)
  - script: |
      git clone https://$(System.AccessToken)@dev.azure.com/yourorg/yourproject/_git/yourproject.wiki wiki
      cp -r .doc-site/* wiki/
      cd wiki
      git config user.email "pipeline@azuredevops.com"
      git config user.name "Azure Pipeline"
      git add .
      git commit -m "Update documentation [skip ci]"
      git push origin HEAD:wikiMaster
    displayName: 'Publish Documentation to Wiki'
    condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')

GitLab CI/CD

Basic Pipeline

Generate documentation on each push to the main branch and deploy to GitLab Pages:

# Run pipeline on merge requests and main branch commits
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

stages:
  - build
  - test
  - documentation
  - deploy

build:
  stage: build
  image: mcr.microsoft.com/dotnet/sdk:10.0
  script:
    - dotnet restore
    - dotnet build --no-restore -c Release
  artifacts:
    paths:
      - "src/**/bin/Release/"
    expire_in: 1 hour

test:
  stage: test
  image: mcr.microsoft.com/dotnet/sdk:10.0
  needs:
    - build
  script:
    - dotnet test --no-restore --no-build -c Release --verbosity minimal

documentation:
  stage: documentation
  image: mcr.microsoft.com/dotnet/sdk:10.0
  needs:
    - build
  script:
    - dotnet tool install --global kampose
    - export PATH="$PATH:$HOME/.dotnet/tools"
    - kampose build
  artifacts:
    paths:
      - .doc-site/
    expire_in: 1 day

# Only deploy to GitLab Pages on main branch (not on merge requests)
pages:
  stage: deploy
  needs:
    - documentation
  script:
    - mkdir -p public
    - cp -r .doc-site/* public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"