Development Guide¶

This guide will help you set up a development environment for working on Medium Converter.

Prerequisites¶

Python 3.11 or newer
Poetry for dependency management
Git for version control

Getting Started¶

Clone the Repository¶

git clone https://github.com/MarcusElwin/medium-converter.git
cd medium-converter

Install Dependencies¶

# Install all dependencies including development tools
poetry install --all-extras

# Or without optional dependencies
poetry install

Activate the Virtual Environment¶

poetry shell

Project Structure¶

medium-converter/
├── medium_converter/            # Main package
│   ├── __init__.py              # Public API & version
│   ├── cli.py                   # CLI interface
│   ├── core/                    # Core functionality
│   │   ├── __init__.py
│   │   ├── fetcher.py           # HTTP client
│   │   ├── parser.py            # HTML parsing
│   │   ├── auth.py              # Authentication
│   │   └── models.py            # Data models
│   ├── exporters/               # Format exporters 
│   │   ├── __init__.py
│   │   ├── base.py              # Base exporter
│   │   ├── markdown.py          # Markdown exporter
│   │   └── ...
│   ├── llm/                     # LLM integration
│   │   ├── __init__.py
│   │   ├── config.py            # Configuration
│   │   ├── enhancer.py          # Content enhancement
│   │   └── ...
│   └── utils/                   # Utilities
│       ├── __init__.py
│       └── helpers.py           # Helper functions
├── tests/                       # Test suite
│   ├── conftest.py              # Test fixtures
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── docs/                        # Documentation
├── examples/                    # Example scripts
├── pyproject.toml               # Project configuration
└── README.md                    # Project readme

Development Workflow¶

Running Tests¶

# Run all tests
pytest

# Run with coverage report
pytest --cov=medium_converter

# Run specific test file
pytest tests/unit/test_models.py

Code Style and Linting¶

The project uses Black, Ruff, and MyPy for code quality:

# Format code with Black
black medium_converter tests

# Run linter
ruff medium_converter tests

# Run type checks
mypy medium_converter

Building Documentation¶

# Build documentation
mkdocs build

# Serve documentation locally
mkdocs serve

Adding Features¶

Adding a New Exporter¶

Create a new file in medium_converter/exporters/ (e.g., html.py)
Implement the exporter class that inherits from BaseExporter
Implement the required methods (especially export())
Register the format in medium_converter/cli.py
Add tests in tests/unit/exporters/
Add documentation in docs/user-guide/formats/

Example:

# medium_converter/exporters/html.py
from typing import Optional, Union, TextIO
from .base import BaseExporter
from ..core.models import Article

class HTMLExporter(BaseExporter):
    """Export Medium articles to HTML format."""

    def export(self, article: Article, output: Optional[Union[str, TextIO]] = None) -> str:
        """Export an article to HTML.

        Args:
            article: The article to export
            output: Optional output file path or file-like object

        Returns:
            The exported content as string
        """
        # Implementation here
        html_content = f"<!DOCTYPE html>\n<html>\n<head>\n<title>{article.title}</title>\n</head>\n<body>\n"
        # ... more implementation

        # Write to file if specified
        if output:
            if isinstance(output, str):
                with open(output, 'w', encoding='utf-8') as f:
                    f.write(html_content)
            else:
                output.write(html_content)

        return html_content

Adding a New LLM Provider¶

Create or modify the provider implementation in medium_converter/llm/providers.py
Add the provider to the LLMProvider enum in medium_converter/llm/config.py
Implement the client class that inherits from LLMClient
Update the get_llm_client function to include your provider
Add relevant tests
Add documentation

Submitting Changes¶

Create a new branch: git checkout -b feature/your-feature-name
Make your changes and commit them with descriptive messages
Run tests to ensure everything is working
Push your branch: git push origin feature/your-feature-name
Create a pull request on GitHub

Release Process¶

Update version in pyproject.toml
Update changelog with your changes
Run the release script: ./scripts/publish.sh
Create a new release on GitHub

Code Conventions¶

Use Google style docstrings
Follow PEP 8 style guidelines
Write comprehensive tests for new features
Keep functions small and focused
Document all public APIs
Use type hints for all functions and methods