Documentation Tooling Selection for Dashtam¶

Evaluation of modern documentation tools (MkDocs, Sphinx, Docusaurus) to establish automated, hybrid documentation system for FastAPI/Python project with API reference generation, deployment automation, and professional user experience.

Context¶

Dashtam is a FastAPI-based financial data aggregation platform. Currently, documentation exists as Markdown files in /docs directory, with API reference auto-generated by FastAPI's OpenAPI. Need to establish comprehensive documentation system that serves multiple audiences (end users, API consumers, developers).

Current State¶

Documentation stored in /docs directory (Markdown files)
FastAPI auto-generates API reference at /docs and /redoc endpoints
No automated documentation build/deploy process
No unified documentation site for users
Developer-facing docs exist, but user-facing guides missing

Desired State¶

Automated documentation generation from Google-style docstrings
Professional documentation site with search, navigation, dark mode
CI/CD automated builds and deployments
Integrated diagrams (Mermaid, PlantUML)
Multi-audience documentation (users, API consumers, developers)
Free hosting solution (GitHub Pages or ReadTheDocs)

Constraints¶

Tech Stack: FastAPI, Python 3.13, already using Markdown
Docstring Style: Google-style docstrings project-wide
Budget: Free tools only (GitHub Pages hosting preferred)
Maintenance: Small team, minimize complexity
Integration: Must integrate with existing GitHub Actions CI/CD

Problem Statement¶

Dashtam needs a modern documentation tooling solution that auto-generates API reference from Python docstrings, provides professional user-facing guides, supports diagrams/visuals, and deploys automatically via CI/CD—all while remaining free and maintainable by a small team.

Why This Matters¶

Business Impact:

User Onboarding: Good docs reduce support burden, improve adoption
Developer Experience: Clear API docs accelerate integration
Professional Credibility: High-quality docs signal mature product

Technical Impact:

Maintainability: Docs-as-code keeps documentation in sync with code
Automation: CI/CD reduces manual deploy work
Discoverability: Search and navigation improve documentation usability

Research Questions¶

Which documentation tool best supports auto-generating API reference from Python Google-style docstrings?
What is the best balance between ease-of-use, features, and professional appearance?
Which tool integrates most easily with FastAPI, GitHub Actions, and free hosting (GitHub Pages)?
How can we support diagrams (Mermaid, PlantUML) in documentation?
What is the industry standard for Python/FastAPI project documentation?

Options Considered¶

Docs-as-Code Philosophy¶

All options follow modern "Docs-as-Code" principle:

📂 Store documentation alongside source code (/docs directory)
✍️ Write in Markdown or reStructuredText
🔄 Version with Git, reviewed via Pull Requests
⚙️ Automate building/publishing via CI/CD
🧩 Keep docs in sync with code (auto-generation from docstrings)

Documentation Audiences¶

Audience	Purpose	Content Type	Example Topics
End Users / Clients	Learn how to use your product	Guides, Tutorials, Walkthroughs	Getting Started, Authentication, Using the Dashboard
API Consumers	Understand the API endpoints	API Reference, Examples, Data Models	REST Endpoints, Request/Response Schemas
Developers (Internal)	Maintain or extend the codebase	Docstrings, Architecture Docs	Internal APIs, System Architecture, CI/CD Setup

Option 1: MkDocs + Material Theme¶

Description: Lightweight static site generator for Markdown documentation with professional Material Design theme.

Pros:

✅ Lightweight & Fast: Minimal setup, fast builds
✅ Beautiful UI: Material Design theme with dark mode, search
✅ Easy GitHub Pages Deploy: One command deployment
✅ Strong Plugin Ecosystem: mkdocstrings (docstring generation), Mermaid diagrams, etc.
✅ Markdown Native: Works with existing docs
✅ Python Friendly: Built in Python, easy for Python devs

Cons:

❌ Limited PDF Export: Not as robust as Sphinx for PDF generation
❌ Fewer Output Formats: Primarily HTML (vs Sphinx's multiple formats)

Complexity: Low

Cost: Free (open source)

Option 2: Sphinx + ReadTheDocs¶

Description: Powerful documentation generator used by Python projects, with rich cross-referencing and multiple output formats.

Pros:

✅ Industry Standard: Used by Python, Django, Flask, FastAPI
✅ Rich Cross-References: Excellent for API documentation
✅ Multiple Output Formats: HTML, PDF, ePub, LaTeX
✅ ReadTheDocs Integration: Free hosting with auto-builds
✅ Mature Ecosystem: Extensive plugin library

Cons:

❌ Complex Setup: Steeper learning curve, more configuration
❌ reST Format: reStructuredText less familiar than Markdown (though Markdown supported)
❌ Heavier: Longer build times for large projects

Complexity: Medium-High

Cost: Free (open source)

Option 3: Docusaurus¶

Description: Modern documentation framework by Facebook/Meta, built on React with excellent versioning support.

Pros:

✅ Modern UI: Beautiful, React-based interface
✅ Versioning Out-of-Box: Excellent multi-version support
✅ Multilingual: Built-in internationalization
✅ Interactive Components: Can embed React components

Cons:

❌ Node.js Dependency: Adds JavaScript tooling to Python project
❌ Heavier Setup: More complex than MkDocs
❌ Overkill for Small Projects: Best for large, versioned docs

Complexity: Medium

Cost: Free (open source)

Option 4: GitHub Pages (Plain Markdown)¶

Description: Simple hosting of Markdown/HTML files directly from GitHub repository.

Pros:

✅ Simple: No build step needed
✅ Free: Built into GitHub
✅ Zero Config: Works out of box

Cons:

❌ No Search: Lacks search functionality
❌ No Versioning: No version management
❌ Basic UI: Plain GitHub Pages theme
❌ No Docstring Generation: Manual API docs only

Complexity: Very Low

Cost: Free

Analysis¶

Comparison Matrix:

Criterion	MkDocs + Material	Sphinx + ReadTheDocs	Docusaurus	GitHub Pages	Weight
Ease of Use	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	High
Python Integration	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐	Critical
Professional UI	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	High
Docstring Generation	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	⭐	Critical
Diagram Support	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐	Medium
GitHub Actions	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	High
Free Hosting	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Medium

Winner: MkDocs + Material Theme:

Best balance of ease-of-use, features, and professional appearance
Excellent Python integration via mkdocstrings plugin
Works natively with existing Markdown documentation
Minimal setup complexity for small team
Strong plugin ecosystem (Mermaid, awesome-pages, mkdocstrings)

Industry Research: Real-World Examples:

FastAPI: Uses MkDocs Material (https://fastapi.tiangolo.com/)
Pydantic: Uses MkDocs Material (https://docs.pydantic.dev/)
SQLModel: Uses MkDocs Material (https://sqlmodel.tiangolo.com/)
Python Core: Uses Sphinx (https://docs.python.org/)
Django: Uses Sphinx (https://docs.djangoproject.com/)

Best Practices:

Docs-as-code: Version control, peer review, CI/CD automation
Auto-generate API reference from docstrings
Include diagrams for architecture and workflows
Provide multi-audience content (users, API consumers, developers)
Follow Google Developer Style Guide for writing quality

Decision¶

MkDocs + Material Theme:

Key Factors:

Best Fit for FastAPI Ecosystem: FastAPI itself uses MkDocs Material, making it the de facto standard
Ease of Use: Minimal learning curve, fast setup for small team
Python Native: Built in Python, integrates seamlessly with Python projects
Docstring Generation: mkdocstrings plugin auto-generates API reference from Google-style docstrings
Professional Appearance: Material Design theme provides modern, polished UI
Free & Simple Deployment: One-command deploy to GitHub Pages
Diagram Support: Mermaid plugin enables inline diagrams

Decision Criteria Met:

✅ Docstring Generation: mkdocstrings supports Google-style docstrings perfectly
✅ Professional UI: Material theme provides modern, searchable interface
✅ Easy GitHub Integration: Simple GitHub Actions workflow
✅ Diagram Support: Mermaid2 plugin for flowcharts/diagrams
✅ Free Hosting: GitHub Pages deployment built-in
✅ Low Maintenance: Small team can manage easily

Consequences¶

Positive Consequences:

✅ Fast Implementation: Can set up complete documentation site in 1-2 days
✅ Industry Alignment: Using same tooling as FastAPI, Pydantic, SQLModel
✅ Developer Experience: Python devs already familiar with Markdown and MkDocs
✅ Professional Appearance: Material theme provides polished, modern UI
✅ Automation: CI/CD removes manual deployment burden
✅ Maintainability: Docs-as-code keeps documentation in sync with code

Negative Consequences:

⚠️ Limited PDF Export: MkDocs PDF generation not as robust as Sphinx (acceptable trade-off)
⚠️ Single Output Format: Primarily HTML (vs Sphinx's HTML/PDF/ePub) (acceptable for web-first docs)

Risks:

Risk 1: Plugin Maintenance
Impact: If mkdocstrings plugin becomes unmaintained, API reference generation breaks
Mitigation: Plugin is actively maintained, widely used; can switch to Sphinx if needed
Risk 2: GitHub Pages Outage
Impact: Documentation site unavailable during GitHub outage
Mitigation: Can quickly redeploy to Netlify/Vercel as backup; GitHub uptime is 99.9%+

Implementation¶

Phase 1: Setup MkDocs Infrastructure:

Install MkDocs and Material theme: uv add mkdocs-material
Install plugins: uv add mkdocstrings mkdocs-mermaid2-plugin mkdocs-awesome-pages-plugin
Create mkdocs.yml configuration file
Set up docs/ directory structure

Phase 2: Migrate Existing Docs:

Review existing /docs Markdown files
Organize into user guides, API reference, architecture sections
Add index.md (documentation homepage)
Configure navigation in mkdocs.yml

Phase 3: Auto-Generate API Reference:

Configure mkdocstrings for Google-style docstrings
Create reference pages for key modules
Test API reference generation

Phase 4: CI/CD Automation:

Create GitHub Actions workflow (.github/workflows/docs.yml)
Configure mkdocs gh-deploy command
Test automated deployment to GitHub Pages

Migration Strategy:

Existing Markdown documentation in /docs can be used as-is with minimal changes. MkDocs will build static site from existing files.

Rollback Plan:

If MkDocs proves insufficient:

Immediate: Continue using existing /docs Markdown files (no functionality lost)
Migrate to Sphinx: Markdown files work with Sphinx via recommonmark plugin
Timeline: Can rollback within 1 day

Success Metrics:

Metric 1: Setup Time - Complete MkDocs setup in < 2 days
Metric 2: Build Time - Documentation builds in < 30 seconds
Metric 3: Team Adoption - 100% of developers can update docs via Markdown
Metric 4: User Satisfaction - Positive feedback on documentation quality

Follow-Up¶

Future Considerations:

Versioning: Add multi-version docs as API evolves (Material theme supports versioning)
Search Analytics: Add Plausible or Fathom analytics to track popular docs
OpenAPI Integration: Auto-generate endpoint docs from OpenAPI spec
Internationalization: Add multi-language support if expanding globally

Review Schedule:

First Review: 1 month after launch (assess usage, gather feedback)
Regular Review: Quarterly (evaluate if additional features needed)
Major Review: Annually (reassess tooling landscape, consider migrations)

References¶

MkDocs Documentation
Material for MkDocs
mkdocstrings - Python docstring generation
Google Developer Style Guide - Writing quality standards
FastAPI Documentation - Example of MkDocs Material in action
Pydantic Documentation - Another excellent MkDocs Material example

Document Information¶

Template: research-template.md Created: 2025-10-15 Last Updated: 2025-10-17