Contributing to Documentation¶

This guide explains how to contribute to and work with the Morphium documentation.

Viewing the Documentation¶

Online¶

Visit the published documentation at: https://sboesebeck.github.io/morphium/

Local Development¶

Install MkDocs and Material theme:
```
pip install mkdocs-material
```
Serve locally:
```
mkdocs serve
```
Then open http://127.0.0.1:8000
Build static site:
```
mkdocs build
```
Output will be in the site/ directory.

Documentation Structure¶

docs/
├── index.md                          # Home page
├── overview.md                       # Getting started overview
├── architecture-overview.md          # Architecture details
├── developer-guide.md                # Developer guide
├── messaging.md                      # Messaging system
├── api-reference.md                  # API reference
├── configuration-reference.md        # Configuration options
├── performance-scalability-guide.md  # Performance tuning
├── production-deployment-guide.md    # Production deployment
├── monitoring-metrics-guide.md       # Monitoring and metrics
├── security-guide.md                 # Security best practices
├── troubleshooting-guide.md          # Troubleshooting
└── howtos/                           # How-to guides
    ├── basic-setup.md
    ├── migration-v5-to-v6.md
    ├── inmemory-driver.md
    ├── aggregation-examples.md
    ├── caching-examples.md
    ├── cache-patterns.md
    ├── field-names.md
    └── messaging-implementations.md

Automated Deployment¶

The documentation is automatically deployed to GitHub Pages when changes are pushed to the master or develop branch.

GitHub Actions Workflow¶

File: .github/workflows/deploy-docs.yml
Triggers on: Push to master/develop with changes to docs/** or mkdocs.yml
Manual trigger: Available via GitHub Actions UI

How it works:¶

Checks out the repository
Installs Python and MkDocs dependencies
Builds the documentation site
Deploys to the gh-pages branch
GitHub Pages serves the content

The Material theme provides: - Tabbed Navigation: Top-level categories - Sidebar Navigation: Nested page structure - Search: Full-text search across all docs - Dark/Light Mode: Theme switcher - Code Highlighting: Syntax highlighting for code blocks - Mobile Responsive: Works on all devices - Table of Contents: Per-page TOC on the right

Editing Documentation¶

Edit Markdown files in the docs/ directory
Add new pages to mkdocs.yml navigation
Test locally with mkdocs serve
Commit and push to trigger automatic deployment

Markdown Extensions¶

Supported features: - Admonitions: !!! note, !!! warning, etc. - Code Blocks: Triple backticks with syntax highlighting - Tables: Standard Markdown tables - Tabbed Content: Using pymdownx.tabbed - Task Lists: - [ ] and - [x]

Theme Configuration¶

The Material theme is configured in mkdocs.yml: - Colors: Indigo primary/accent - Features: Navigation tabs, expand sections, search suggestions - Plugins: Search, tags - Social: GitHub repository link

Troubleshooting¶

Issue: Theme not found

pip install mkdocs-material

Issue: Build fails

mkdocs build --strict  # Shows detailed errors

Issue: Navigation not updating - Check mkdocs.yml nav structure - Ensure file paths are correct relative to docs/

Contributing¶

When adding new documentation: 1. Place in appropriate directory (docs/ or docs/howtos/) 2. Update mkdocs.yml navigation 3. Use consistent heading levels (H1 for title, H2 for sections) 4. Add code examples where applicable 5. Test locally before committing