Development Guide¶

Overview¶

Guide for contributing to docling-graph development.

What's Included: - Contributing guidelines - Development setup - Code standards - Testing requirements - GitHub workflow - Release process

Quick Start¶

1. Fork and Clone¶

# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/docling-graph.git
cd docling-graph

2. Setup Development Environment¶

# Install with all dependencies
uv sync --extra dev

# Verify installation
uv run python -c "import docling_graph; print(docling_graph.__version__)"

3. Create Branch¶

# Create feature branch
git checkout -b feature/my-feature

# Or bug fix branch
git checkout -b fix/issue-123

4. Make Changes¶

# Edit code
# Add tests
# Update documentation

5. Run Tests¶

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=docling_graph --cov-report=html

6. Submit Pull Request¶

# Commit changes
git add .
git commit -s -m "feat: add new feature"

# Push to your fork
git push origin feature/my-feature

# Create PR on GitHub

Development Topics¶

📝 Contributing¶

Contributing Guidelines Official contribution guidelines for the project.

Code of conduct
Contribution workflow
Issue reporting
Pull request process
Legal requirements (DCO)

🔧 GitHub Workflow¶

GitHub Workflow
Working with GitHub and CI/CD.

Branch strategy
Commit conventions
CI/CD pipeline
Automated testing
Code quality checks

🚀 Release Process¶

Release Process
How releases are managed.

Version numbering
Release checklist
Changelog management
Publishing process
Documentation updates

Development Setup¶

System Requirements¶

Python 3.10+
Git
uv package manager
(Optional) GPU with CUDA for local inference

Install Development Dependencies¶

# Full development setup
uv sync --extra dev

# This installs:
# - Core dependencies
# - Local inference (vLLM, transformers)
# - Remote API clients
# - Development tools (pytest, ruff, mypy)
# - Documentation tools (mkdocs)

Verify Setup¶

# Check Python version
python --version  # Should be 3.10+

# Check uv
uv --version

# Run tests
uv run pytest

# Check code quality
uv run ruff check .
uv run mypy docling_graph

Code Standards¶

Style Guide¶

We follow PEP 8 with some modifications:

Line length: 100 characters
Use type hints for all functions
Docstrings for all public APIs
Format with ruff format

Type Checking¶

All code must pass mypy:

uv run mypy docling_graph

Linting¶

Code must pass ruff checks:

# Check code
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Format code
uv run ruff format .

Testing Requirements¶

Test Coverage¶

Minimum 80% code coverage
All new features must have tests
Bug fixes must include regression tests

Running Tests¶

# All tests
uv run pytest

# Specific test file
uv run pytest tests/unit/test_config.py

# Specific test
uv run pytest tests/unit/test_config.py::test_pipeline_config

# With coverage
uv run pytest --cov=docling_graph --cov-report=html

# Fast tests only (skip slow)
uv run pytest -m "not slow"

Writing Tests¶

"""Test example."""

import pytest
from docling_graph import PipelineConfig

def test_pipeline_config_creation():
    """Test PipelineConfig can be created."""
    config = PipelineConfig(
        source="test.pdf",
        template="templates.Test"
    )
    assert config.source == "test.pdf"
    assert config.backend == "llm"  # Default

def test_pipeline_config_validation():
    """Test PipelineConfig validates inputs."""
    with pytest.raises(ValueError):
        PipelineConfig(
            source="test.pdf",
            template="templates.Test",
            backend="invalid"  # Should fail
        )

Documentation¶

Building Documentation¶

# Install mkdocs
uv add --dev mkdocs mkdocs-material

# Serve locally
uv run mkdocs serve

# Build static site
uv run mkdocs build

Documentation Standards¶

All public APIs must be documented
Include code examples
Use clear, concise language
Cross-reference related docs
Keep examples up to date

Project Structure¶

docling-graph/
├── docling_graph/           # Source code
│   ├── __init__.py
│   ├── pipeline.py
│   ├── config.py
│   ├── protocols.py
│   ├── exceptions.py
│   ├── core/               # Core modules
│   ├── llm_clients/        # LLM integrations
│   ├── pipeline/           # Pipeline orchestration
│   └── cli/                # CLI commands
│
├── tests/                  # Test suite
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   ├── fixtures/          # Test fixtures
│   └── mocks/             # Mock objects
│
├── docs/                   # Documentation
│   ├── 01-introduction/
│   ├── installation/
│   └── ...
│
├── examples/               # Example code
│   ├── scripts/
│   └── templates/
│
├── .github/               # GitHub configuration
│
├── pyproject.toml         # Project configuration
├── README.md              # Project README
├── CHANGELOG.md           # Version history
└── LICENSE                # License file

Common Tasks¶

Add New Feature¶

Create issue describing feature
Create feature branch
Implement feature with tests
Update documentation
Submit pull request

Fix Bug¶

Create issue describing bug
Create fix branch
Write failing test
Fix bug
Verify test passes
Submit pull request

Update Documentation¶

Edit markdown files in docs/
Test locally with mkdocs serve
Submit pull request

Add New LLM Client¶

Implement LLMClientProtocol
Add to llm_clients/
Add tests
Update documentation
Submit pull request

Getting Help¶

Resources¶

GitHub Issues - Report bugs, request features
GitHub Discussions - Ask questions
GitHub Repository - Source code and issues

Communication¶

Be respectful and constructive
Provide clear, detailed information
Include code examples when relevant
Follow up on feedback

Next Steps¶

GitHub Workflow → - Understand the workflow
Release Process → - Learn about releases
GitHub Workflow → - Development workflow