Merge pull request #94 from WenbinWL/docs/add-mkdocs-site-v2

docs: add MkDocs documentation site

Author: shinybrar

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: 'Reason for manual documentation deployment'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    if: ${{ github.repository == 'opencadc/deployments' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/[email protected]
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Deploy documentation
+        run: uv run mkdocs gh-deploy --force

docs/index.md

@@ -0,0 +1,55 @@
+# CANFAR Deployments
+
+Welcome to the operational documentation for deploying and maintaining the CANFAR Science Platform. This repository contains Helm charts, Kubernetes configurations, CI/CD automation, and operations runbooks that power the platform infrastructure.
+
+## What You'll Find Here
+
+This documentation is designed for **platform operators, DevOps engineers, and infrastructure maintainers** who deploy, configure, and manage CANFAR services.
+
+<div class="grid cards" markdown>
+
+- :material-kubernetes: **Helm Charts**
+
+    Reusable deployment templates for CANFAR services with configurable values and environment overlays.
+
+- :material-rocket-launch: **Release Automation**
+
+    Automated CI/CD pipelines using GitHub Actions and Release Please for Helm chart versioning.
+
+- :material-file-document: **Operations Runbooks**
+
+    Step-by-step procedures for releases, rollbacks, monitoring, and troubleshooting production deployments.
+
+- :material-cog: **Configuration Management**
+
+    Environment-specific overlays, secrets management, and Kubernetes resource definitions for staging and production.
+
+- :material-book-open-variant: **Documentation**
+
+    Automated MkDocs site deployment with operations guides and platform runbooks.
+
+- :material-shield-check: **Code Quality**
+
+    Pre-commit hooks, linting, and security scanning for infrastructure-as-code.
+
+</div>
+
+## Quick Links
+
+- [**CI/CD Pipelines**](operations/ci-cd.md) - Understand GitHub Actions workflows for documentation and code quality
+- [**Release Process**](operations/release-process.md) - Follow the Helm chart release process and CANFAR platform schedule
+- [**GitHub Repository**](https://github.com/opencadc/deployments/) - Browse source code, Helm charts, and configurations
+
+## Getting Started
+
+If you're new to CANFAR deployments:
+
+1. Review the [Release Process](operations/release-process.md) to understand our deployment workflow
+2. Explore the [CI/CD Pipelines](operations/ci-cd.md) documentation to see how automation works
+3. Check the [GitHub repository](https://github.com/opencadc/deployments/) for Helm charts and configuration files
+
+## Contributing
+
+This is an operational repository for CANFAR platform infrastructure. Changes follow the standard pull request workflow with Release Please automation for versioning and changelog generation.
+
+For questions or support, contact the CADC operations team or visit the [main CANFAR documentation](https://www.opencadc.org/canfar/).

docs/logo.png

@@ -0,0 +1,44 @@
+# CI/CD Pipelines
+
+The deployments repository uses GitHub Actions to automate documentation and code quality tasks.
+
+## Documentation Deployment (`docs.yml`)
+
+Automatically builds and deploys the MkDocs documentation site to GitHub Pages.
+
+### Triggers
+
+- Pushes to `main` that modify `docs/**`, `mkdocs.yml`, or `pyproject.toml`
+- Manual dispatch with required reason field
+
+### Workflow Steps
+
+1. **Checkout**: Fetches full git history (required for git-revision-date plugin)
+2. **Install uv**: Sets up the uv package manager
+3. **Setup Python**: Installs Python using uv
+4. **Install dependencies**: Runs `uv sync` to install all dependencies from `pyproject.toml`
+5. **Deploy**: Runs `uv run mkdocs gh-deploy --force` to build and publish to `gh-pages` branch
+
+### Requirements
+
+- `contents: write` permission for pushing to `gh-pages` branch
+- Dependencies managed in `pyproject.toml`:
+  - `mkdocs-material` - Material theme for MkDocs
+  - `mkdocs-git-revision-date-localized-plugin` - Git revision dates in docs
+
+## Pre-commit Checks (`pre-commit.yml`)
+
+Runs pre-commit hooks on all files to ensure code quality and consistency.
+
+### Triggers
+
+- Pull requests to `main`
+- Manual dispatch
+
+### What it checks
+
+- YAML syntax and formatting
+- JSON formatting
+- File permissions and naming
+- Security scanning for hardcoded secrets
+- Python code quality (if applicable)

docs/operations/ci-cd.md

@@ -0,0 +1,65 @@
+# Operations
+
+Operational guides and runbooks for managing CANFAR platform infrastructure, releases, and deployments.
+
+## Overview
+
+This section provides comprehensive documentation for platform operators managing CANFAR deployments. Whether you're releasing new versions, troubleshooting issues, or maintaining infrastructure, these guides will help you follow best practices and ensure reliable operations.
+
+<div class="grid cards" markdown>
+
+- [:material-pipe: __CI/CD Pipelines__ <small>GitHub Actions workflows</small>](ci-cd.md)
+- [:material-rocket-launch-outline: __Release Process__ <small>Release playbook and procedures</small>](release-process.md)
+
+</div>
+
+## Key Responsibilities
+
+### Release Management
+
+- Coordinate releases using Release Please automation
+- Review and merge release PRs with proper approvals
+- Monitor post-release workflows and verify deployments
+- Manage hotfixes and rollback procedures when needed
+
+### Infrastructure Operations
+
+- Deploy Helm charts and configuration overlays
+- Manage environment-specific configurations (staging, production)
+- Monitor platform health and respond to incidents
+- Maintain secrets and access controls
+
+### CI/CD Maintenance
+
+- Keep GitHub Actions workflows up to date
+- Monitor workflow runs and troubleshoot failures
+- Update documentation and configuration files
+
+## Tools & Technologies
+
+The CANFAR deployment infrastructure relies on:
+
+- **Kubernetes** - Container orchestration platform
+- **Helm** - Package manager for Kubernetes applications
+- **GitHub Actions** - CI/CD automation and workflows
+- **Release Please** - Automated release management and changelog generation
+- **MkDocs Material** - Documentation site generation
+- **uv** - Python package and dependency management
+
+## Getting Help
+
+For operational support or questions:
+
+- Check the relevant runbook in this documentation
+- Review recent GitHub Actions workflow runs for error logs
+- Contact the CADC operations team
+- Consult the [main CANFAR documentation](https://www.opencadc.org/canfar/)
+
+## Best Practices
+
+1. **Always follow the release checklist** - Skip no steps to ensure consistent, reliable releases
+2. **Test in staging first** - Validate changes in staging before promoting to production
+3. **Monitor post-deployment** - Watch metrics and logs after every deployment
+4. **Document incidents** - Capture lessons learned and update runbooks
+5. **Keep secrets secure** - Rotate credentials regularly and limit access
+6. **Maintain audit trails** - All changes go through pull requests with proper reviews

docs/operations/index.md

@@ -0,0 +1,90 @@
+# Release Process
+
+Documentation for releasing Helm charts and platform configuration for the CANFAR Science Platform.
+
+## CANFAR Release Cycle
+
+The CANFAR Science Platform uses a version format `YYYY.Q` for quarterly releases:
+
+- **2025.1** - Q1 2025 release
+- **2025.2** - Q2 2025 release
+
+Between releases, **hotfix patches** may be released as needed for critical issues.
+
+## Helm Chart Releases
+
+Each Helm chart in this repository is versioned independently:
+
+- Charts follow semantic versioning (`MAJOR.MINOR.PATCH`)
+- Release Please automation manages changelog and version bumps
+- Each chart has its own release cycle and `CHANGELOG.md`
+
+## Branching Model
+
+- `main` is the integration branch - all work merges via pull requests
+- Use conventional commits for automatic changelog generation
+- Hotfixes branch from the latest release tag and merge back to `main`
+
+## Release Workflow
+
+### 1. Making Changes
+
+- Create a pull request to `main`
+- Use conventional commit messages (e.g., `feat:`, `fix:`, `docs:`)
+- Add appropriate labels for changelog categorization
+- Ensure all CI checks pass
+
+### 2. Release Please Automation
+
+Release Please automatically:
+
+- Detects changes to Helm charts
+- Determines version bump based on conventional commits
+- Updates `CHANGELOG.md` and `Chart.yaml`
+- Creates a release PR for each affected chart
+
+### 3. Review and Merge
+
+- Review the generated changelog and version bump
+- Verify Helm chart values and configuration
+- Obtain required approvals
+- Merge the release PR to create tags and GitHub releases
+
+### 4. Deployment
+
+After release PR is merged:
+
+- Git tag is created automatically
+- GitHub release is published with changelog
+- Deploy to staging environment first
+- Run validation and smoke tests
+- Deploy to production after successful validation
+
+## Hotfix Process
+
+For critical issues requiring immediate patches:
+
+1. Create `hotfix/<issue>` branch from affected release tag
+2. Apply fix and create PR to `main`
+3. Release Please generates patch release PR
+4. Follow standard review and merge process
+5. Deploy hotfix after testing
+
+## Pre-deployment Checklist
+
+Before deploying a Helm chart release:
+
+- ✅ Review CHANGELOG for all changes
+- ✅ Verify chart values match intended configuration
+- ✅ Check for breaking changes or migrations
+- ✅ Ensure dependent services are compatible
+- ✅ Prepare rollback plan
+
+## Rollback Strategy
+
+If issues are detected after deployment:
+
+1. Roll back to previous Helm chart version
+2. Document issue and root cause
+3. Create hotfix branch to address problem
+4. Follow hotfix process for patch release

docs/operations/release-process.md

@@ -0,0 +1,49 @@
+[data-md-color-scheme="canfar"] {
+  --md-primary-fg-color:               #005493;
+  --md-accent-fg-color:                #F5AA1C;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-hue: 210;
+  --md-primary-fg-color: #005493;
+  --md-accent-fg-color: #F5AA1C;
+}
+
+@keyframes heart {
+  0%, 40%, 80%, 100% {
+    transform: scale(1);
+  }
+  20%, 60% {
+    transform: scale(1.15);
+  }
+}
+.heart {
+  animation: heart 1000ms infinite;
+}
+
+/* Indentation for nested items in the primary sidebar navigation */
+:root {
+  /* Tune this to increase/decrease the indent */
+  --canfar-nav-indent: 0.6rem;
+  --canfar-nav-border-color: var(--md-default-fg-color--lighter);
+}
+
+/* Clear active page: color only (no left bar, no bold) */
+:root {
+  --canfar-nav-active-color: var(--md-accent-fg-color);
+}
+
+/* Current page link and its parent trail */
+.md-sidebar--primary .md-nav--primary .md-nav__link--active,
+.md-sidebar--primary .md-nav--primary .md-nav__item--active > .md-nav__link,
+.md-sidebar--primary .md-nav--primary .md-nav__item--active > label.md-nav__link,
+.md-sidebar--primary .md-nav--primary a.md-nav__link[aria-current="page"],
+.md-sidebar--primary .md-nav--primary a.md-nav__link[aria-current="location"] {
+  color: var(--canfar-nav-active-color);
+}
+
+/* Indent nested nav via container padding (no borders) */
+.md-sidebar--primary .md-nav--primary .md-nav__item > .md-nav {
+  margin-left: 0;
+  padding-left: var(--canfar-nav-indent);
+}