Skip to content

# Deployment Guide

This documentation is automatically deployed to GitHub Pages using GitHub Actions. Here's how it works and how to manage deployments.

## Automatic Deployment

The documentation is automatically deployed when changes are pushed to the `main` or `master` branch. The deployment process:

1. Triggers on push to main/master
2. Sets up Python environment
3. Installs required dependencies
4. Builds the documentation
5. Deploys to the `gh-pages` branch

### GitHub Actions Workflow

The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`. This is the single source of truth for documentation deployment:

    name: Deploy MkDocs
    on:
      push:
        branches:
          - main
          - master
      workflow_dispatch:  # Allow manual trigger

## Manual Deployment

If needed, you can deploy manually using:

    # Create a virtual environment
    python -m venv venv

    # Activate the virtual environment
    source venv/bin/activate

    # Install dependencies
    pip install -r docs/requirements.txt

    # Build the documentation
    mkdocs build

    # Deploy to GitHub Pages
    mkdocs gh-deploy --force

## Best Practices

### 1. Documentation Updates

- Test locally before pushing: `mkdocs serve`
- Verify all links work
- Ensure images are optimized
- Check mobile responsiveness

### 2. Version Control

- Keep documentation in sync with code versions
- Use meaningful commit messages
- Tag important documentation versions

### 3. Content Guidelines

- Use consistent formatting
- Keep navigation structure logical
- Include examples where appropriate
- Maintain up-to-date screenshots

### 4. Maintenance

- Regularly review and update content
- Check for broken links
- Update dependencies
- Monitor GitHub Actions logs

## Troubleshooting

### Common Issues

1. Failed Deployments
2. Check GitHub Actions logs
3. Verify dependencies are up to date

4. Ensure all required files exist

5. Broken Links

6. Run `mkdocs build --strict`
7. Use relative paths in markdown

8. Check case sensitivity

9. Style Issues

10. Verify theme configuration
11. Check CSS customizations
12. Test on multiple browsers

## Configuration Files

### requirements.txt

Create a requirements file for documentation dependencies:

    mkdocs-material
    mkdocs-minify-plugin
    mkdocs-git-revision-date-plugin
    mkdocs-mkdocstrings
    mkdocs-social-plugin
    mkdocs-redirects

## Monitoring

- Check GitHub Pages settings
- Monitor build status in Actions tab
- Verify site accessibility

## Workflow Features

### Caching

The workflow implements caching for Python dependencies to speed up deployments: - Pip cache for Python packages - MkDocs dependencies cache

### Deployment Checks

Several checks are performed during deployment: 1. Link validation with `mkdocs build --strict` 2. Build verification 3. Post-deployment site accessibility check

### Manual Triggers

You can manually trigger deployments using the "workflow_dispatch" event in GitHub Actions.

## Cleanup

To clean up duplicate workflow files, run:

    # Make the script executable
    chmod +x scripts/cleanup-workflows.sh

    # Run the cleanup script
    ./scripts/cleanup-workflows.sh

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings