Agent Coding Guidelines for md-exporter

Agent Coding Guidelines for md-exporter

This document provides essential information for agentic coding agents working in the md-exporter repository.

🔧 Build, Lint, and Test Commands

Package Management

• Primary: uv package manager is used for dependency management
• Fallback: pip if uv is not available
• Python Requirement: Python 3.11 or higher required

Code Quality and Formatting

Lint and Format Code

# Alternative: Run from project root using provided script
./dev.reformat.sh

Run Tests

# Run all tests
test/bin/run_all_tests.sh 

# Run specific test file
test/bin/test_md_to_docx.sh 

or

uv run pytest test/skills/test_md_to_docx.py

Development Scripts

• Main CLI: scripts/md-exporter (shell script wrapper)
• Test Scripts: Individual test scripts in test/bin/

📝 Code Style Guidelines

Formatting and Style

• Line Length: 120 characters maximum
• Line Ending: LF (Unix-style)
• Indentation: 4 spaces (not tabs)
• Quotes: Use double quotes for strings unless single quotes are preferred for specific cases
• End of File: All files must end with newline character

Python Style Standards

Import Organization

# Standard library imports
from pathlib import Path
from tempfile import NamedTemporaryFile

# Third-party imports
from pypandoc import convert_file

# Local imports (relative paths)
from scripts.utils.markdown_utils import get_md_text

Type Hints and Annotations

• Use Python 3.11+ union syntax: Path | None (not Optional[Path])
• All function parameters and return values should have type hints
• Use pathlib.Path for file paths, not strings

Function Documentation

def convert_md_to_docx(
    md_text: str, output_path: Path, template_path: Path | None = None, is_strip_wrapper: bool = False
) -> None:
    """
    Convert Markdown text to DOCX format

    Args:
        md_text: Markdown text to convert
        output_path: Path to save the output DOCX file
        template_path: Optional path to DOCX template file
        is_strip_wrapper: Whether to remove code block wrapper if present

    Raises:
        ValueError: If input processing fails
        Exception: If conversion fails
    """

Naming Conventions

• Files: snake_case.py for Python files
• Functions: snake_case() for functions and methods
• Classes: PascalCase for classes
• Constants: UPPER_SNAKE_CASE for constants
• Private Methods: Prefix with single underscore _private_method()

Error Handling

• Always handle exceptions properly, never use empty catch blocks
• Raise specific exceptions with descriptive messages
• Use context managers (with statements) for resource management
• Clean up temporary files in finally blocks

Ruff Linting Rules

The project uses these ruff rules:

• UP: pyupgrade rules for modern Python features
• I: isort for import organization
• E402: Module level import not at top of file
• F401: Imported but unused

Configuration is in .ruff.toml.

📁 Project Structure

Core Directories

• scripts/: Main entry points and core logic
  • services/: Conversion service modules (svc_*.py)
  • parser/: CLI parsers for each tool (cli_*.py)
  • utils/: Shared utility functions
• test/: Test files organized by functionality
  • skills/: Tests for each conversion tool
  • bin/: Shell script test runners
• assets/: Template files and static resources
  • template/: DOCX and PPTX template files

Key Service Patterns

Each conversion tool follows this pattern:

• Service: scripts/services/svc_md_to_X.py - Core conversion logic
• Parser: scripts/parser/cli_md_to_X.py - CLI argument parsing
• CLI: scripts/md-exporter X - Shell script entry point
• Test: test/skills/test_md_to_X.py - Unit tests

File Processing Patterns

• Use pathlib.Path for all file operations
• Implement proper cleanup for temporary files
• Support custom template files when available
• Handle both relative and absolute file paths correctly

🧪 Testing Guidelines

Test Structure

• Tests extend TestBase class
• Use run_script() method for CLI testing
• Verify output files exist and are not empty
• Use descriptive test method names: test_tool_name()

Test Data

• Input files are in test/resources/
• Output files should go to test_output/
• Each tool has corresponding test resources

Running Individual Tests

# Run specific tool test
cd test/bin && ./test_md_to_html.sh

# Run with pytest directly
uv run pytest test/skills/test_md_to_docx.py -v

🚫 Important Constraints

1. Python Version: Always use Python 3.11+ features and syntax
2. Package Manager: Prefer uv over pip for development
3. Path Handling: Use pathlib.Path exclusively for file paths
4. Error Handling: Never suppress exceptions or use empty catch blocks
5. Code Quality: Always run ruff check --fix before committing
6. Testing: Run tests after any changes to ensure functionality

🔄 Development Workflow

1. Make changes following the code style guidelines
2. Run linting: dev/reformat.sh
3. Run tests: test/bin/run_all_tests.sh
4. Verify all tools still work correctly
5. Test individual tools via CLI scripts