Documentation System

This directory contains the automated documentation generation system for Helix Toolkit using DocFX.

Overview

The documentation system automatically generates:

  • API Documentation: Extracted from XML documentation comments in C# source code
  • Articles: Conceptual documentation and guides (stored in articles/)
  • Static Site: A browseable website with search functionality

Building Documentation Locally

Prerequisites

Quick Start

On Windows

cd Source
build-doc.cmd

On Linux/macOS

cd Source
./build-doc.sh

The documentation will be built and served locally at http://localhost:8080. Press Ctrl+C to stop the server.

Building Without Serving

To build the documentation without starting the local server (useful in CI environments):

Windows

set CI=True
build-doc.cmd

Linux/macOS

CI=true ./build-doc.sh

The generated documentation will be in Documentation/_site/.

Automated Documentation Generation

GitHub Actions Workflow

Documentation is automatically built and deployed via GitHub Actions:

  1. On Pull Requests: Documentation is built to verify it compiles correctly
  2. On Push to main/develop: Documentation is built and deployed to GitHub Pages

Viewing Published Documentation

Once deployed, the documentation is available at:

  • GitHub Pages: https://helix-toolkit.github.io/helix-toolkit/

Documentation Structure

Documentation/
├── api/              # Auto-generated API documentation
├── articles/         # Hand-written articles and guides
│   ├── intro.md
│   └── toc.yml
├── images/           # Images used in documentation
├── docfx.json        # DocFX configuration
├── index.md          # Documentation homepage
└── toc.yml           # Top-level table of contents

Writing Documentation

API Documentation

Add XML documentation comments to your C# code:

/// <summary>
/// Represents a 3D model in the scene.
/// </summary>
/// <remarks>
/// This class provides functionality for loading and rendering 3D models.
/// </remarks>
public class Model3D
{
    /// <summary>
    /// Gets or sets the position of the model in 3D space.
    /// </summary>
    /// <value>A Vector3 representing the position.</value>
    public Vector3 Position { get; set; }
    
    /// <summary>
    /// Loads a 3D model from the specified file.
    /// </summary>
    /// <param name="filename">The path to the model file.</param>
    /// <returns>True if the model was loaded successfully; otherwise, false.</returns>
    /// <exception cref="FileNotFoundException">Thrown when the file does not exist.</exception>
    public bool Load(string filename)
    {
        // Implementation
    }
}

Adding Articles

  1. Create a new .md file in the articles/ directory
  2. Add the article to articles/toc.yml:
- name: Getting Started
  href: getting-started.md
- name: Your New Article
  href: your-new-article.md

Markdown Features

DocFX supports:

  • Standard Markdown syntax
  • Code blocks with syntax highlighting
  • Cross-references to API documentation using @ApiNamespace.ClassName
  • Alerts: > [!NOTE], > [!WARNING], > [!TIP]
  • Tables, images, and more

Example:

# My Article

This article explains how to use @HelixToolkit.Wpf.HelixViewport3D.

> [!TIP]
> Make sure to initialize the viewport before adding models.

## Code Example

'''csharp
var viewport = new HelixViewport3D();
viewport.Camera = new PerspectiveCamera();
'''

Configuration

The documentation system is configured in docfx.json. Key settings:

  • metadata: Specifies which projects to include in API documentation
  • build.content: Defines which content files to include
  • build.template: Specifies the documentation theme (default + modern)
  • build.globalMetadata: Site-wide settings like title, footer, etc.

Troubleshooting

Build Errors

If the documentation build fails:

  1. Check XML Documentation: Ensure your project files have <GenerateDocumentationFile>true</GenerateDocumentationFile>
  2. Restore NuGet Packages: Run dotnet restore in the Source/ directory
  3. Clear DocFX Cache: Delete Documentation/_site/ and rebuild

Missing API Documentation

If some classes/methods are missing from the documentation:

  1. Ensure they are public or protected (private members are not documented by default)
  2. Check that the project is included in docfx.json under metadata.src.files
  3. Verify XML comments exist for the member
  • Use relative paths for internal links: [Link](../api/Namespace.Class.yml)
  • Use @ for API cross-references: @Namespace.ClassName

Additional Resources

Edit this page