Contributing

Contributions to Inkfeed are welcome! Here's how to get set up.

Development Setup

1. Clone the repository:

   git clone <your-repo-url>
   cd inkfeed
   

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # macOS/Linux
   

3. Install in editable mode with dev dependencies:

   pip install -e ".[dev]"
   

4. (Optional) Install Sleepscreen dependencies:

   pip install -e ".[sleepscreen]"
   playwright install chromium
   

Project Structure

See the Architecture Overview for a detailed breakdown.

The key directories are:

• inkfeed/archiver/ — Source fetchers
• inkfeed/output/ — Format writers
• inkfeed/templates/ — Jinja2 templates
• inkfeed/utils/ — Shared utilities
• tests/ — Test suite

Code Style

• Python 3.11+ with type hints
• Use from __future__ import annotations for modern type syntax
• Follow existing patterns in the codebase
• Keep functions focused and well-documented

Adding a New Source

1. Create inkfeed/archiver/your_source.py
2. Implement a class with __init__(source, output_dir) and run() methods
3. Return an ArchiveResult from run()
4. Register in ARCHIVER_MAP in main.py
5. Add tests in tests/

Adding a New Output Format

1. Create inkfeed/output/your_format.py
2. Implement a FormatWriter subclass
3. Register in WRITER_MAP in main.py
4. Add tests in tests/

Pull Requests

• Keep PRs focused on a single change
• Include tests for new functionality
• Update documentation if applicable
• Ensure all tests pass before submitting