📚 Implement MkDocs with Material Theme for Documentation Build System

[httpdss]

🎯 Overview

This PR implements MkDocs with the Material theme to generate HTML documentation from the existing docs/ folder, integrates it with GitHub Actions, and ensures proper build artifacts management.

🔧 Changes Made

Core Setup

• ✅ MkDocs Configuration: Created mkdocs.yml with Material theme configuration
• ✅ Documentation Structure: Configured MkDocs to build from ./docs/ source directory
• ✅ Output Directory: Set output directory to ./site/docs/ (gitignored)
• ✅ Dependencies: Added requirements.docs.txt for MkDocs and Material theme

GitHub Actions Integration

• ✅ Workflow Updates: Modified .github/workflows/deploy-pages.yml
  • Added Python setup step with dependency caching
  • Added MkDocs dependency installation
  • Added MkDocs build step before deployment
  • Updated workflow triggers to include docs/**, mkdocs.yml, and requirements.docs.txt changes
  • Added fetch-depth: 0 for git-revision-date-localized plugin

Repository Management

• ✅ Git Ignore: Updated .gitignore to exclude ./site/docs/ directory
• ✅ Build Artifacts: Generated documentation is treated as build artifact (not committed)
• ✅ Existing Structure: Maintained existing ./site/ structure for other static assets

🚀 Features Implemented

Material Theme Configuration

• Light/Dark Mode Toggle: Automatic theme switching
• Navigation: Tabs, sections, and expandable navigation
• Search: Enhanced search with highlighting and sharing
• Code Features: Syntax highlighting with copy buttons
• Mobile Responsive: Optimized for mobile devices

MkDocs Extensions

• Admonitions: Call-out boxes for notes, warnings, etc.
• Code Highlighting: Syntax highlighting with line numbers
• Tabbed Content: Support for tabbed sections
• Table of Contents: Auto-generated TOC with permalinks
• Git Integration: Last modified dates from Git history

Navigation Structure

Organized documentation into logical sections:

• Getting Started: Installation, Quick Start, Usage
• Configuration: YAML Config, Template Variables, File Handling, Mappings
• Advanced Features: Custom Structures, Hooks, GitHub Integration, Schema
• Development: Dev Setup, Completion, Contributing
• Reference: Examples, Articles, Known Issues, Funding

🧪 Testing

• ✅ Local Build: mkdocs build successfully generates static HTML
• ✅ Output Directory: Documentation generated in ./site/docs/
• ✅ Git Ignore: Generated files properly excluded from version control
• ✅ Material Theme: Theme applied with proper styling and features
• ✅ Navigation: All documented pages accessible through navigation

📝 Usage

Local Development

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

# Serve documentation locally with live reload
mkdocs serve

# Build documentation
mkdocs build

Production Deployment

GitHub Actions will automatically:

1. Install Python and MkDocs dependencies
2. Build documentation with mkdocs build
3. Deploy to GitHub Pages alongside existing static assets

🔗 Closes

Closes #77

🚦 Checklist

• MkDocs installed and configured with Material theme
• Documentation builds from ./docs/ source directory
• Output directory set to ./site/docs/
• mkdocs.yml configuration file created
• GitHub Actions workflow updated with MkDocs build step
• Python dependencies installation added to workflow
• Workflow triggers updated for documentation changes
• .gitignore updated to exclude ./site/docs/
• Build artifacts properly managed (not committed)
• Local development supports mkdocs serve
• Documentation successfully builds and generates HTML

🔍 Additional Notes

• The build process shows some warnings about missing documentation files referenced in existing docs. These can be addressed in future updates.
• The Material theme provides excellent SEO, mobile responsiveness, and user experience.
• The git-revision-date-localized plugin shows last modified dates for each page.
• All existing static assets in ./site/ remain unchanged and will continue to work.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.74%. Comparing base (21f19d5) to head (41504db).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #78   +/-   ##
=======================================
  Coverage   68.74%   68.74%           
=======================================
  Files          23       23           
  Lines        1331     1331           
  Branches      181      181           
=======================================
  Hits          915      915           
  Misses        374      374           
  Partials       42       42           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.