[CHORE]: GitHub Actions to build docs, with diagrams and test report, and deploy to GitHub Pages using MkDocs on every push to main

[crivetimihai]

🔧 Chore Summary

Set up automated documentation generation in GitHub Actions to build docs, generate architecture diagrams, and deploy to GitHub Pages using MkDocs on every push to main branch.

---

🧱 Area Affected

• GitHub Actions / CI Pipelines
• Build system or Makefile
• Docs or spellcheck
• Containerization (Docker/Podman)

---

⚙️ Context / Rationale

Currently, documentation generation is a manual process requiring developers to:

1. Run make docs locally to generate handsdown documentation
2. Run make images to create architecture diagrams
3. Manually commit and push documentation updates

This creates several problems:

• Documentation drift - docs get out of sync with code changes
• Developer friction - extra manual steps slow down development
• Inconsistency - different environments may generate different outputs
• Barriers to contribution - contributors need local tooling setup

Automating this process will:

• Ensure docs are always up-to-date with latest code
• Remove manual burden from developers
• Provide consistent, reproducible documentation builds
• Enable automatic deployment to GitHub Pages
• Integrate with existing MkDocs configuration

---

📦 Related Make Targets

• make docs - generate documentation with handsdown + images + sbom
• make images - generate architecture diagrams (code2flow, snakefood, pyreverse)
• make sbom - generate software bill of materials
• make install - may need updates for CI dependencies (e.g.graphviz)

---

📋 Acceptance Criteria

• Create .github/workflows/docs.yml workflow file
• Workflow triggers on push to main branch and manual dispatch
• Install all required dependencies (graphviz, code2flow, handsdown, etc.)
• Include unit test report make test in generated documentation
• Run existing make docs target to generate documentation
• Set up MkDocs integration and configuration
• Deploy generated docs to GitHub Pages
• Handle git authentication for committing back to repo
• Add appropriate caching for dependencies and build artifacts
• Workflow runs successfully without manual intervention
• Generated docs are accessible via GitHub Pages
• Include status badge in README for docs build status

---

🧩 Additional Notes

Required GitHub Actions workflow structure:

name: 📚 Generate Documentation
on:
  push:
    branches: [ main ]
    paths: 
      - 'mcpgateway/**'
      - 'docs/**'
      - 'README.md'
      - 'mkdocs.yml'
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write
      id-token: write

Dependencies to install in CI:

• Python environment with project dependencies
• graphviz system package for dot/SVG generation
• code2flow for code flow diagrams
• snakefood3 for dependency graphs
• pylint for pyreverse UML generation
• handsdown for API documentation
• mkdocs + mkdocs-material for site generation

Key workflow steps:

1. Checkout code with full history
2. Set up Python + install dependencies
3. Install system packages (graphviz)
4. Run make docs to generate all documentation
5. Configure git for automated commits
6. Commit any changes back to repo
7. Deploy to GitHub Pages using official actions

Configuration needs:

• Update mkdocs.yml to point to generated docs location
• Ensure .gitignore doesn't exclude generated documentation
• Set up GitHub Pages to deploy from workflow
• Configure branch protection to allow workflow commits

Performance considerations:

• Cache Python dependencies and system packages
• Only regenerate docs when relevant files change
• Consider using artifacts to store intermediate build outputs

[Suraj-kumar00]

Hi there,
Hope you're doing well.
Can I pick up this issue?

[ChrisPC-39]

Hi @Suraj-kumar00

I started working on this in this PR: #475

It's currently in draft as I am working on it. If you want to help, I can give you access to the branch and work on it together. If you feel better starting from scratch let me know.