Documentation Pipeline

Loading…

Documentation Pipeline

Relevant source files

• .github/workflows/build-docs.yml

Purpose and Scope

This document describes the automated documentation generation and deployment system that converts repository content into a browsable static site hosted on GitHub Pages. The pipeline uses the DeepWiki documentation generation tool to analyze the codebase and produce structured technical documentation.

For information about the continuous integration testing pipeline, see Continuous Integration. For Git workflow and secret management practices, see Version Control Best Practices.

Overview

The documentation pipeline is implemented as a GitHub Actions workflow that automatically generates and deploys documentation to GitHub Pages. The workflow is defined in .github/workflows/build-docs.yml:1-81 and operates independently of the main CI pipeline. It uses the deepwiki-to-mdbook action to analyze the repository structure and generate mdBook-formatted documentation.

Key Characteristics

Sources: .github/workflows/build-docs.yml:1-12

Workflow Triggers

The pipeline supports two activation mechanisms configured in the on section of the workflow:

Scheduled Execution

The workflow executes automatically every Sunday at midnight UTC. This weekly cadence ensures documentation stays reasonably current without excessive build frequency. The cron expression "0 0 * * 0" specifies minute 0, hour 0, any day of month, any month, day 0 (Sunday).

Manual Dispatch

The workflow_dispatch trigger enables manual workflow execution through the GitHub Actions UI. This allows documentation regeneration on-demand when significant repository changes occur or when immediate documentation updates are required.

Sources: .github/workflows/build-docs.yml:3-7

Permissions and Concurrency

Permission Model

The workflow requires three specific permissions defined at the workflow level:

Concurrency Control

The pages concurrency group ensures only one documentation deployment runs at a time. The cancel-in-progress: false setting prevents cancellation of in-flight deployments when new builds are triggered, ensuring documentation builds complete even if overlapping triggers occur.

Sources: .github/workflows/build-docs.yml:9-16

Build Job Architecture

The build job executes on ubuntu-latest and consists of five sequential steps that prepare, generate, and package the documentation.

flowchart TD
    Trigger["Trigger Event\n(schedule or workflow_dispatch)"]
subgraph BuildJob["build job (ubuntu-latest)"]
CheckoutStep["actions/checkout@v4\nClone repository"]
ResolveStep["Resolve repository and book title\nShell script logic"]
PrepareStep["Prepare output directory\nrm -rf output && mkdir"]
GenerateStep["jzombie/deepwiki-to-mdbook@main\nGenerate documentation"]
UploadStep["actions/upload-pages-artifact@v3\nPackage for Pages"]
end
    
    subgraph DeployJob["deploy job (ubuntu-latest)"]
DeployStep["actions/deploy-pages@v4\nPublish to GitHub Pages"]
end
    
 
   Trigger --> CheckoutStep
 
   CheckoutStep --> ResolveStep
 
   ResolveStep --> PrepareStep
 
   PrepareStep --> GenerateStep
 
   GenerateStep --> UploadStep
 
   UploadStep --> DeployStep
    
 
   ResolveStep -.->|repo_value title_value| GenerateStep

Workflow Execution Diagram

Sources: .github/workflows/build-docs.yml:18-69

Repository and Title Resolution

The “Resolve repository and book title” step implements dynamic configuration logic that determines which repository to document and what title to use.

Resolution Logic

The step defined in .github/workflows/build-docs.yml:25-52 executes a shell script with the following logic:

Output Variables

The resolution step produces two output variables accessible to subsequent steps:

Sources: .github/workflows/build-docs.yml:25-52

Documentation Generation

The core documentation generation step uses the jzombie/deepwiki-to-mdbook@main action to analyze the repository and produce mdBook output.

Generation Step Configuration

Input Parameters

Output Directory Structure

The generation step produces the following directory structure:

output/
└── book/
    ├── index.html
    ├── *.html (generated pages)
    └── (mdBook assets)

The output/book/ directory contains the complete static site ready for deployment.

Sources: .github/workflows/build-docs.yml:59-64

GitHub Pages Deployment

The deployment process uses GitHub’s standard Pages deployment actions to publish the generated documentation.

Artifact Upload

The actions/upload-pages-artifact@v3 action packages the ./output/book directory as a GitHub Actions artifact specifically formatted for Pages deployment. This artifact is stored temporarily and consumed by the deployment job.

Deployment Job

The deploy job:

• Depends on successful completion of the build job via needs: build
• Targets the github-pages environment
• Exposes the deployment URL via steps.deployment.outputs.page_url
• Uses actions/deploy-pages@v4 to publish the artifact

Sources: .github/workflows/build-docs.yml:66-80

Pipeline Data Flow

Sources: .github/workflows/build-docs.yml:1-81

Pipeline Behavior and Characteristics

Idempotency

The pipeline is fully idempotent. Multiple executions with the same repository state produce identical documentation output. The preparation step .github/workflows/build-docs.yml:54-57 explicitly removes and recreates the output directory to ensure clean builds.

Failure Modes

Build Duration

Typical pipeline execution times:

• Repository checkout: 5-10 seconds
• Documentation generation: 2-5 minutes (varies with repository size)
• Artifact upload: 10-30 seconds
• Pages deployment: 30-60 seconds
• Total pipeline duration: ~3-7 minutes

Sources: .github/workflows/build-docs.yml:18-80

Integration with Repository

The documentation pipeline operates independently but maintains integration with the repository through several mechanisms:

Repository Settings Requirements

For the pipeline to function, the repository must have GitHub Pages enabled:

1. Navigate to Settings → Pages
2. Set Source to “GitHub Actions”
3. No branch selection required (Actions-based deployment)

Permission Configuration

The workflow uses the default GITHUB_TOKEN with elevated permissions defined in .github/workflows/build-docs.yml:9-12 No additional secrets or tokens are required.

Workflow Dependencies

Sources: .github/workflows/build-docs.yml:9-16

Customization and Extension

Modifying Schedule

To change the build frequency, edit the cron expression in .github/workflows/build-docs.yml:5-6:

Customizing Book Title

The book title can be overridden by:

1. Manual workflow dispatch with custom book_title input
2. Modifying the derived title logic in .github/workflows/build-docs.yml:41-46

Output Directory

The output directory is hardcoded as ./output in multiple steps:

• Preparation: .github/workflows/build-docs.yml56
• Generation: .github/workflows/build-docs.yml64
• Upload: .github/workflows/build-docs.yml69

Changing the directory requires updating all three references.

Sources: .github/workflows/build-docs.yml:4-69

Monitoring and Verification

Workflow Execution Status

View workflow runs at: https://github.com/<owner>/<repo>/actions/workflows/build-docs.yml

Each run shows:

• Trigger type (scheduled or manual)
• Execution time
• Build job status
• Deploy job status
• Deployed Pages URL

Deployment Verification

After successful deployment:

1. Navigate to repository Settings → Pages
2. Verify the displayed URL matches expected documentation site
3. Access the URL to confirm documentation content

Troubleshooting Failed Builds

Check the workflow logs for common issues:

• Repository checkout fails : Verify repository permissions
• DeepWiki generation fails : Check repository structure and content
• Artifact upload fails : Verify GitHub Actions storage limits
• Pages deployment fails : Confirm Pages is enabled and configured for Actions

Sources: .github/workflows/build-docs.yml:1-81

Dismiss

Refresh this wiki

Enter email to refresh