MkDocs Setup for OK CLI¶

Overview¶

This project now includes comprehensive documentation using:

MkDocs: Static site generator for documentation
Material for MkDocs: Professional Material Design theme
mkdocstrings: Automatic API documentation from Python docstrings

Files Created¶

Configuration Files¶

mkdocs.yml - Main MkDocs configuration with Material theme settings
docs.py - Convenience script for documentation management

Documentation Structure¶

docs/
├── index.md                    # Home page
├── user-guide/
│   ├── installation.md        # Installation instructions
│   ├── usage.md              # Usage guide with examples
│   └── commands.md           # Command reference
├── api/
│   ├── cli.md                # CLI module documentation (auto-generated)
│   ├── commands.md           # Commands API (auto-generated)
│   └── templates.md          # Template system documentation
└── development/
    ├── contributing.md       # Contributing guidelines
    └── changelog.md          # Release notes

site/                          # Generated documentation (ignored in git)

Quick Start¶

Build Documentation¶

python docs.py build

Serve Documentation Locally¶

python docs.py serve

Then visit: http://127.0.0.1:8000

Deploy to GitHub Pages¶

python docs.py deploy

Features¶

✅ Material Design Theme - Modern, responsive design ✅ Auto-generated API Docs - Extracted from Python docstrings ✅ Search - Full-text search across all pages ✅ Dark Mode - Automatic theme switching ✅ Mobile Responsive - Works on all devices ✅ Syntax Highlighting - Code highlighting with copy button

Configuration¶

The mkdocs.yml file contains:

Site metadata (name, description, author)
Theme configuration (Material Design theme)
Plugin configuration (search, mkdocstrings)
Navigation structure
Markdown extensions

Key Markdown Extensions¶

pymdownx.highlight - Code syntax highlighting
pymdownx.superfences - Fenced code blocks
pymdownx.tabbed - Content tabs
pymdownx.emoji - Emoji support
admonition - Callout boxes
attr_list - Element attributes
tables - Markdown tables
toc - Table of contents

Adding New Documentation¶

Create a markdown file in the appropriate docs/ subdirectory
Add the file path to the nav section in mkdocs.yml
Run python docs.py build to regenerate

API Documentation¶

The API reference is automatically generated from:

Module docstrings in ok_cli/cli.py
Command function docstrings in ok_cli/commands/*.py

To improve your API documentation:

Add comprehensive docstrings to your Python code
Use Google-style docstrings (configured in mkdocs.yml)
Document parameters, return values, and exceptions

Example:

def new(name: str):
    """Create a new React Native app.

    Args:
        name: The name of the app to create

    Returns:
        None

    Raises:
        ValueError: If the name is invalid
    """
    pass

GitHub Pages Deployment¶

To enable automatic deployment to GitHub Pages:

Ensure your repository is on GitHub
Go to Settings > Pages
Select "Deploy from a branch"
Choose "gh-pages" branch as the source
Run python docs.py deploy to build and push documentation

Local Development¶

For local testing before deployment:

# Install development dependencies
pip install -e ".[dev]"

# Serve documentation with live reload
python docs.py serve

# Clean build artifacts
python docs.py clean

Troubleshooting¶

Documentation not building¶

Check that all markdown files exist
Verify navigation paths in mkdocs.yml
Run mkdocs build -v for verbose output

API documentation not showing¶

Ensure Python modules have docstrings
Check that module paths are correct in docs/api/*.md
Run mkdocs build with verbose logging

Deployment issues¶

Verify GitHub repository is properly configured
Check git remote is set to GitHub
Ensure you have permission to push to the repository

Next Steps¶

Customize the theme colors in mkdocs.yml under theme.palette
Add more pages to the user guide as needed
Improve docstrings in Python code for better API docs
Set up GitHub Pages deployment
Consider adding a blog or tutorial section