mkdocs-flow 0.1.0
Automated Documentation Project Generator - Create beautiful MkDocs documentation projects with ease
License: MIT
Requires Python: <4.0,>=3.11
Keywords: documentation, mkdocs, generator, cli, automation

# DocuFlow

[![PyPI version](https://badge.fury.io/py/mkdocs-flow.svg)](https://badge.fury.io/py/mkdocs-flow)
[![Python Support](https://img.shields.io/pypi/pyversions/mkdocs-flow.svg)](https://pypi.org/project/mkdocs-flow/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

> **Automated Documentation Project Generator** - Create beautiful MkDocs documentation projects with PDF export and version management

DocuFlow is a powerful CLI tool that automates the creation of professional documentation projects using MkDocs and the Material theme. It handles everything from project setup to Git repository creation, CI/CD configuration, PDF generation, and versioned documentation deployment.

## ✨ Features

### Core Features
- 🚀 **Quick Project Setup** - Generate complete documentation projects in seconds
- 🎨 **Beautiful Templates** - Pre-configured MkDocs Material themes
- 🔧 **Git Integration** - Automatic GitHub/GitLab repository creation
- 📦 **CI/CD Ready** - GitHub Actions and GitLab CI configurations included
- 🎯 **Multiple Templates** - Choose from basic or full-featured setups
- 🔐 **Secure Authentication** - Token management with keyring integration
- 📱 **Rich CLI** - Beautiful terminal interface with progress indicators

### PDF Generation
- 📄 **PDF Export** - Generate professional PDFs from your markdown documentation
- 📚 **Version History** - Automatically include git tag history in PDFs
- 🔗 **Table of Contents** - Clickable TOC with customizable depth
- 🖼️ **Image Embedding** - Base64 image encoding for standalone PDFs
- 📊 **Mermaid Diagrams** - Optional diagram rendering to images
- 📦 **Multi-Section PDFs** - Generate different PDFs from different doc sections
- 🎁 **Release Packages** - Create ZIP files with PDFs and additional files

### Version Management
- 🏷️ **Versioned Docs** - Full integration with [mike](https://github.com/jimporter/mike) for versioned documentation
- 🔄 **Git Tag Sync** - Automatic alignment between git tags and documentation versions
- 📌 **Version Aliases** - Support for "latest", "stable", and custom aliases
- 🌐 **Version Selector** - Automatic version picker in your documentation site
- 🚀 **Automated Deployment** - CI/CD workflows handle versioned deployments automatically

## 🚀 Quick Start

### Installation

```bash
# Install with pip
pip install mkdocs-flow

# Or with Poetry
poetry add mkdocs-flow

# Install with PDF generation support
pip install "mkdocs-flow[diagrams]"  # Includes Mermaid diagram rendering
```

**System Requirements for PDF Generation:**

Ubuntu/Debian:
```bash
sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev libcairo2
```

macOS:
```bash
brew install cairo pango gdk-pixbuf libffi
```

### Basic Usage

```bash
# Initialize a new documentation project
docuflow init my-awesome-docs

# Navigate to your project
cd my-awesome-docs

# Serve documentation locally
docuflow serve

# Build documentation
docuflow build

# Create a versioned release
docuflow version-create --version 1.0 --alias latest

# Generate PDFs
docuflow generate-pdf

# Deploy to GitHub/GitLab Pages (with versioning)
git push origin main
git tag 1.0.0
git push origin 1.0.0  # Triggers automatic versioned deployment
```

## 📖 Documentation

### Commands

#### `docuflow init [PROJECT_NAME]`

Initialize a new documentation project with interactive setup.

**Options:**
- `--name TEXT` - Project name
- `--description TEXT` - Project description  
- `--author TEXT` - Author name
- `--email TEXT` - Author email
- `--git-provider [github|gitlab]` - Git provider
- `--private` - Create private repository
- `--template [basic|full]` - Project template
- `--no-remote` - Skip remote repository creation
- `--config-file PATH` - Configuration file

**Example:**
```bash
docuflow init my-project \
  --description "My awesome project documentation" \
  --author "John Doe" \
  --email "john@example.com" \
  --template full \
  --private
```

#### `docuflow serve [PROJECT_PATH]`

Serve documentation locally for development.

**Example:**
```bash
docuflow serve ./my-project
```

#### `docuflow build [PROJECT_PATH]`

Build documentation site.

**Options:**
- `--clean` - Clean build directory before building

**Example:**
```bash
docuflow build --clean
```

#### `docuflow deploy [PROJECT_PATH]`

Deploy documentation to GitHub/GitLab Pages.

**Options:**
- `--force` - Force deployment without confirmation

**Example:**
```bash
docuflow deploy --force
```

#### `docuflow config`

Manage DocuFlow configuration and authentication tokens.

#### `docuflow templates`

List available project templates.

#### `docuflow version-create`

Create a new documentation version with mike and git tag.

**Options:**
- `--version, -v TEXT` - Version number (e.g., 1.0, 1.0.0)
- `--title TEXT` - Version title
- `--alias, -a TEXT` - Version aliases (can be used multiple times)
- `--no-tag` - Do not create git tag
- `--message, -m TEXT` - Git tag message

**Example:**
```bash
# Create version 1.0 with "latest" alias
docuflow version-create --version 1.0 --alias latest

# Create version with custom title and multiple aliases
docuflow version-create \
  --version 2.0 \
  --title "Version 2.0 - Major Release" \
  --alias latest \
  --alias stable

# Interactive mode
docuflow version-create
```

#### `docuflow version-list`

List all versions and check alignment between git tags and mike versions.

**Example:**
```bash
docuflow version-list
```

Shows a table with:
- ✓ Aligned versions (both git tag and mike version exist)
- ⚠ Git-only tags (no corresponding mike version)
- ⚠ Mike-only versions (no corresponding git tag)

#### `docuflow generate-pdf`

Generate PDF documentation from markdown files.

**Arguments:**
- `SECTIONS` - Section names to generate (optional, defaults to all)

**Options:**
- `--tag, -t TEXT` - Git tag/version to use
- `--output-dir PATH` - Output directory (default: pdfs)

**Examples:**
```bash
# Generate all configured PDFs
docuflow generate-pdf

# Generate specific sections
docuflow generate-pdf user-guide api-reference

# Generate for a specific version
docuflow generate-pdf --tag 1.0.0

# Custom output directory
docuflow generate-pdf --output-dir releases/v1.0
```

Generated projects also include a standalone `generate_pdf.py` script:

```bash
# In your project directory
poetry run python generate_pdf.py --tag 1.0
```

### Templates

#### Basic Template
- Minimal setup with essential pages and plugins
- Plugins: search, awesome-pages, mermaid2
- Perfect for simple documentation needs

#### Full Template  
- Comprehensive structure with all features enabled
- Plugins: search, awesome-pages, mermaid2, git-revision-date-localized, minify
- Advanced features and optimizations included

### Configuration

DocuFlow stores configuration in `~/.docuflow/config.yml`. You can customize:

- Default git provider (GitHub/GitLab)
- Default theme and template
- Repository visibility preferences
- Plugin configurations

### Authentication

DocuFlow supports secure token storage using keyring:

```bash
# Configure tokens interactively
docuflow config

# Or set environment variables
export GITHUB_TOKEN="your_github_token"
export GITLAB_TOKEN="your_gitlab_token"
```

### PDF Configuration

Generated projects include a `pdf_config.yml` file for customizing PDF generation:

```yaml
# PDF Export Configuration
sections:
  - name: user-guide
    title: "User Guide"
    output: "user-guide.pdf"
    docs_dir: "docs/sections/user-guide"

  - name: api-reference
    title: "API Reference"
    output: "api-reference.pdf"
    docs_dir: "docs/sections/api-reference"

  - name: full-documentation
    title: "Complete Documentation"
    output: "documentation.pdf"
    docs_dir: "docs"

# Version history settings
include_version_history: true

# Table of contents settings
include_toc: true
toc_depth: 3

# Image handling
embed_images: true

# Mermaid diagram rendering (requires playwright)
render_mermaid: false

# Release packaging
create_release_zip: false
release_includes:
  - "*.g4"
  - "*.ebnf"
```

### Version Management with Mike

Generated projects automatically include mike configuration in `mkdocs.yml`:

```yaml
extra:
  version:
    provider: mike
```

The GitHub Actions workflow is pre-configured to:
- Deploy versioned documentation on tag pushes
- Update the "latest" alias automatically
- Maintain version history with a version selector

**Workflow:**
1. Develop documentation on the `main` branch
2. Create a version: `docuflow version-create --version 1.0 --alias latest`
3. Push changes and tags: `git push && git push --tags`
4. GitHub Actions automatically deploys the versioned documentation
5. Users can select versions from the documentation site

## 🛠️ Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/yourusername/docuflow.git
cd docuflow

# Install dependencies
poetry install

# Install pre-commit hooks
pre-commit install

# Run tests
poetry run pytest

# Run linting
poetry run black src tests
poetry run isort src tests
poetry run flake8 src tests
poetry run mypy src
```

### Project Structure

```
docuflow/
├── src/docuflow/              # Source code
│   ├── __init__.py
│   ├── cli.py                 # CLI interface
│   ├── config.py              # Configuration management
│   ├── git_manager.py         # Git operations
│   ├── models.py              # Data models (including PDF config)
│   ├── project_manager.py     # Project orchestration
│   ├── template.py            # Template generation
│   ├── export_utils.py        # Git tag & file utilities
│   ├── pdf_generator.py       # PDF generation engine
│   ├── version_manager.py     # Version management (mike)
│   ├── mermaid_renderer.py    # Mermaid diagram rendering
│   └── templates/             # Project templates
│       ├── export_utils.py.template
│       ├── generate_pdf.py.template
│       └── mermaid_renderer.py.template
├── tests/                     # Test suite
│   ├── test_cli.py
│   ├── test_export_utils.py
│   ├── test_pdf_generator.py
│   ├── test_version_manager.py
│   └── ...
├── docs/                      # Documentation
├── pyproject.toml             # Poetry configuration
├── README.md
└── IMPLEMENTATION_SUMMARY.md  # Implementation details
```

**Generated Project Structure:**

When you create a project with DocuFlow, it includes:

```
my-project/
├── docs/                      # Documentation source
├── mkdocs.yml                 # MkDocs config (with mike)
├── pyproject.toml             # Dependencies (includes mike)
├── pdf_config.yml             # PDF generation config
├── export_utils.py            # Export utilities
├── generate_pdf.py            # PDF generation script
├── mermaid_renderer.py        # Mermaid support
├── .github/workflows/
│   └── deploy-docs.yml        # CI/CD with mike deployment
└── scripts/
    ├── build.sh
    └── serve.sh
```

### Testing

```bash
# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/docuflow

# Run specific test file
poetry run pytest tests/test_cli.py
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
5. Run the test suite (`poetry run pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

### Core Technologies
- [MkDocs](https://www.mkdocs.org/) - The documentation generator
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) - The beautiful theme
- [Click](https://click.palletsprojects.com/) - The CLI framework
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output

### PDF & Versioning
- [WeasyPrint](https://weasyprint.org/) - PDF generation from HTML/CSS
- [Mike](https://github.com/jimporter/mike) - MkDocs version management
- [Pillow](https://python-pillow.org/) - Image processing
- [Playwright](https://playwright.dev/) - Mermaid diagram rendering

### Development Tools
- [Poetry](https://python-poetry.org/) - Dependency management
- [Pytest](https://pytest.org/) - Testing framework
- [Black](https://black.readthedocs.io/) - Code formatting

## 📞 Support

- 📧 Email: antonio.olleros@meaningfuldata.eu
- 🐛 Issues: [GitHub Issues](https://github.com/antonio-olleros/docuflow/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/antonio-olleros/docuflow/discussions)

## 🆕 What's New

### Version 0.2.0 - PDF & Versioning Support

DocuFlow now includes comprehensive PDF generation and version management capabilities!

**New Features:**
- ✅ Generate professional PDFs from markdown with version history
- ✅ Full mike integration for versioned documentation
- ✅ Automatic git tag and version alignment
- ✅ Mermaid diagram rendering in PDFs
- ✅ Multi-section PDF export
- ✅ Release packaging with ZIP files

**New Commands:**
- `docuflow version-create` - Create versioned releases
- `docuflow version-list` - Check version alignment
- `docuflow generate-pdf` - Generate PDFs

See [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) for complete implementation details and the [PDF_VERSIONING_MIGRATION_GUIDE.md](PDF_VERSIONING_MIGRATION_GUIDE.md) for the original feature specifications.

---

**Made with ❤️ for the open source community**