Skip to content

Documentation Deployment

This guide explains how to set up automatic deployment of MkDocs documentation to GitHub Pages.

Automatic Deployment with GitHub Actions

The documentation is automatically built and deployed on every push to the main or master branch.

Initial Setup

  1. Enable GitHub Pages:
  2. Go to your repository on GitHub
  3. Navigate to Settings → Pages
  4. Under Source, select GitHub Actions

  5. Save the changes

  6. Push to trigger deployment: 

    git push origin main

  7. Verify deployment:

  8. Go to Actions tab in your repository
  9. You should see "Deploy Documentation" workflow running
  10. Once complete, your docs will be available at: https://your-username.github.io/tradingbot25/

Manual Deployment

You can also trigger deployment manually:

  1. Go to Actions tab
  2. Select Deploy Documentation workflow
  3. Click Run workflow
  4. Select branch and click Run workflow

Workflow Details

The GitHub Actions workflow (.github/workflows/docs.yml) does the following:

  1. Checks out the repository
  2. Sets up Python 3.12 and uv
  3. Installs dependencies including MkDocs and plugins
  4. Builds documentation using mkdocs build
  5. Deploys to GitHub Pages automatically

Troubleshooting

Documentation not appearing

  1. Check GitHub Pages settings:
  2. Ensure "GitHub Actions" is selected as the source

  3. Check that the workflow has completed successfully

  4. Check workflow logs:

  5. Go to Actions tab
  6. Click on the latest workflow run

  7. Review logs for any errors

  8. Common issues:

  9. Build failures: Check that all dependencies are in pyproject.toml under [project.optional-dependencies.docs]
  10. Import errors: Ensure tradingbot module can be imported (check Python path)
  11. Missing files: Verify all markdown files referenced in mkdocs.yml exist

Update repository URL

If your repository URL changes, update mkdocs.yml:

repo_name: tradingbot25
repo_url: https://github.com/your-username/tradingbot25

Local Testing

Before pushing, test the build locally:

# Install dependencies
uv sync --extra docs

# Build documentation
uv run mkdocs build

# Check for errors
# Output should be in ./site directory

Custom Domain (Optional)

To use a custom domain:

  1. Add a CNAME file to docs/ directory: 

    docs.yourdomain.com

  2. Configure DNS:

  3. Add a CNAME record pointing to your-username.github.io

  4. Update GitHub Pages settings:

  5. Go to Settings → Pages
  6. Enter your custom domain

Next Steps