📚 DocFX Documentation Generation Action

Generate comprehensive documentation using DocFX .NET Global Tool with support for multiple output formats, themes, and hosting options.

Features

📚 Complete DocFX Support - Full integration with DocFX CLI commands and options
🎨 Theme & Template Support - Use built-in or custom themes and templates
🔍 Flexible Configuration - Support for custom docfx.json configurations
📊 Comprehensive Logging - Multiple log levels with optional structured JSON output
🔧 Debug Support - Export raw and view models for troubleshooting
⚡ Performance Options - Configurable parallelism and Git feature control
📈 Detailed Analytics - File counts, sizes, and execution metrics

Usage

Basic Usage

Generate documentation using default docfx.json configuration:

- name: Generate Documentation
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'

Advanced Usage with Custom Configuration

- name: Generate Documentation with Custom Settings
  uses: ./dotnet-docfx-build
  with:
    config: 'docs/docfx.json'
    output: 'documentation'
    theme: 'modern'
    log-level: 'verbose'
    warnings-as-errors: 'true'
    metadata: '{"_appTitle":"My Project","_appFooter":"© 2024 My Company"}'
    xref: 'https://docs.microsoft.com/dotnet/xref/,https://docs.microsoft.com/dotnet/api/'

Debug Mode with Model Export

- name: Generate Documentation with Debug Info
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'
    debug: 'true'
    export-raw-model: 'true'
    export-view-model: 'true'
    debug-output: 'debug-output'

Production Build with Optimizations

- name: Generate Production Documentation
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'
    output: '_site'
    warnings-as-errors: 'true'
    disable-git-features: 'true'
    max-parallelism: '4'
    log-level: 'warning'

Inputs

Required Inputs

None. All inputs are optional with sensible defaults.

Optional Inputs

Input	Description	Default	Example
`config`	Path to the docfx configuration file	`docfx.json`	`docs/docfx.json`
`output`	Output base directory for generated documentation	`_site`	`documentation`
`log-level`	Log level (error, warning, info, verbose, diagnostic)	`info`	`verbose`
`log-file`	Save structured JSON log to specified file	`''`	`docfx.log.json`
`verbose`	Enable verbose logging	`false`	`true`
`warnings-as-errors`	Treat warnings as errors	`false`	`true`
`metadata`	Global metadata in JSON format	`''`	`{"_appTitle":"My App"}`
`xref`	Comma-separated xrefmap URLs	`''`	`https://docs.microsoft.com/dotnet/xref/`
`template`	Template name to apply	`''`	`modern`
`theme`	Theme to use	`default`	`modern`
`debug`	Run in debug mode	`false`	`true`
`debug-output`	Debug output folder	`''`	`debug-output`
`export-raw-model`	Export raw model files	`false`	`true`
`raw-model-output-folder`	Raw model output folder	`''`	`raw-models`
`export-view-model`	Export view model files	`false`	`true`
`view-model-output-folder`	View model output folder	`''`	`view-models`
`max-parallelism`	Maximum parallel processes (0 = auto)	`0`	`4`
`markdown-engine-properties`	Markdown engine parameters (JSON)	`''`	`{"markdigExtensions":["pipes"]}`
`post-processors`	Comma-separated post processor order	`''`	`ExtractSearchIndex,SitemapGenerator`
`disable-git-features`	Disable Git information fetching	`false`	`true`
`docfx-version`	Specific DocFX version to install	`''`	`2.70.0`
`show-summary`	Show action summary	`true`	`false`

Outputs

Output	Description	Example
`output-path`	Full path to generated documentation	`/path/to/_site`
`config-path`	Path to DocFX configuration file used	`/path/to/docfx.json`
`files-count`	Number of files generated	`145`
`output-size`	Total output directory size in bytes	`2048576`

Examples

Multi-Project Documentation

name: Generate Multi-Project Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

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

    - name: Generate API Documentation
      uses: ./dotnet-docfx-build
      with:
        config: 'docs/docfx.json'
        output: 'api-docs'
        metadata: '{"_appTitle":"My API","_appFooter":"Generated by DocFX"}'
        warnings-as-errors: 'true'

    - name: Upload Documentation
      uses: actions/upload-artifact@v4
      with:
        name: api-documentation
        path: api-docs/

Documentation with Custom Theme

- name: Generate Documentation with Custom Theme
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'
    theme: 'modern'
    template: 'custom-template'
    metadata: |
      {
        "_appTitle": "My Project Documentation",
        "_appFooter": "© 2024 My Company. All rights reserved.",
        "_enableSearch": true,
        "_enableNewTab": true
      }
    xref: 'https://docs.microsoft.com/dotnet/xref/,https://docs.microsoft.com/dotnet/api/'
```## Requirements

### Prerequisites

- .NET SDK (any supported version)
- DocFX-compatible project structure
- Valid `docfx.json` configuration file

### Dependencies

- **DocFX Global Tool** - Automatically installed by the action
- **Python 3** - For JSON validation (usually pre-installed)

### Supported Platforms

- ✅ Linux (ubuntu-latest)
- ✅ macOS (macos-latest)
- ✅ Windows (windows-latest)

## Configuration

### DocFX Configuration File

Create a `docfx.json` file in your repository root:

```json
{
  "metadata": [
    {
      "src": [
        {
          "files": ["**/*.csproj"],
          "exclude": ["**/bin/**", "**/obj/**"]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": ["api/**.yml", "api/index.md"]
      },
      {
        "files": ["articles/**.md", "articles/**/toc.yml", "toc.yml", "*.md"]
      }
    ],
    "resource": [
      {
        "files": ["images/**"]
      }
    ],
    "output": "_site",
    "globalMetadata": {
      "_appTitle": "My Project",
      "_appFooter": "© 2024 My Company"
    }
  }
}

Custom Metadata

You can provide additional metadata via the metadata input:

metadata: |
  {
    "_appTitle": "My API Documentation",
    "_appFooter": "© 2024 My Company",
    "_enableSearch": true,
    "_enableNewTab": true,
    "_disableContribution": false,
    "_gitContribute": {
      "repo": "https://github.com/myuser/myrepo",
      "branch": "main"
    }
  }

Theme Customization

Specify custom themes and templates:

theme: 'modern'              # Built-in theme
template: 'custom-template'  # Custom template path

Troubleshooting

Common Issues

❌ Configuration File Not Found

Error: DocFX configuration file not found: docfx.json

Solution: Ensure your docfx.json file exists in the specified path.

- name: Check Configuration
  run: ls -la docfx.json

- name: Generate Documentation
  uses: ./dotnet-docfx-build
  with:
    config: 'path/to/docfx.json'

❌ Build Failures

Error: Documentation generation failed

Solutions:

Enable verbose logging to see detailed errors:
```
log-level: 'verbose'
verbose: 'true'
```
Use debug mode for troubleshooting:
```
debug: 'true'
export-raw-model: 'true'
```
Check your project references and dependencies.

❌ Memory Issues

OutOfMemoryException during generation

Solutions:

Reduce parallelism:
```
max-parallelism: '1'
```
Disable Git features for large repos:
```
disable-git-features: 'true'
```

❌ Template/Theme Issues

Error: Template 'xyz' not found

Solutions:

Use built-in themes:
```
theme: 'default'  # or 'modern'
```
Ensure custom templates are in the correct path.

Debug Mode

Enable comprehensive debugging:

- name: Generate Documentation with Full Debug
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'
    debug: 'true'
    export-raw-model: 'true'
    export-view-model: 'true'
    debug-output: 'debug-files'
    log-level: 'diagnostic'
    log-file: 'docfx-debug.log.json'

This will generate additional files for troubleshooting:

Raw model files (.raw.model.json)
View model files (.view.model.json)
Structured debug log

Performance Optimization

For large documentation sets:

- name: Optimized Documentation Generation
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'
    max-parallelism: '4'           # Adjust based on runner
    disable-git-features: 'true'   # Skip Git info for speed
    log-level: 'warning'           # Reduce log verbosity
    warnings-as-errors: 'false'    # Continue on warnings

Validation

Validate your configuration before generation:

- name: Validate DocFX Configuration
  uses: ./dotnet-docfx-build
  with:
    config: 'docfx.json'
    log-level: 'verbose'

Contributing

When contributing to this action:

Follow the Actions Guidelines
Test with various DocFX configurations
Ensure cross-platform compatibility
Update documentation for new features
Add appropriate error handling and validation

License

This action is distributed under the same license as the repository.

Support

For issues related to:

DocFX functionality: Check DocFX Documentation
Action bugs: Create an issue in this repository
GitHub Actions: Check GitHub Actions Documentation