sabbath-school-reproducer 0.1.2

Download and process Sabbath School lessons from GitHub

📚 Sabbath School Lessons Reproducer

A tool to download, format, and reproduce Sabbath School lessons from historical archives for modern use.

✨ Features

• 📝 YAML-based configuration for easy customization
• 🔄 Automatic downloading of lesson content from GitHub repositories
• 🕰️ Reproduction mode for adapting historical lessons to current dates
• 📑 Professionally formatted PDF generation with customizable styling
• 🎨 Support for custom cover designs
• 🌐 Comprehensive multi-language support (English, Swahili, Luo) with user-modifiable translations

🔧 Requirements

• Python 3.6+
• Dependencies: pyyaml, requests, markdown, weasyprint, beautifulsoup4

💻 Installation

From PyPI

pip install sabbath-school-reproducer

From Source

1. Clone the repository:

git clone https://github.com/sabbathschool/sabbath-school-reproducer.git
cd sabbath-school-reproducer

2. Install the package:

pip install -e .

🚀 Quick Start

1. Initialize with default templates and configuration:

sabbath-school-reproducer init

2. Edit the generated config.yaml file with your desired settings

3. Run the tool with your configuration:

sabbath-school-reproducer run config.yaml

📖 Usage

sabbath-school-reproducer [-h] {init,run} ...

Download and process Sabbath School lessons

options:
  -h, --help     show this help message and exit

Commands:
  {init,run}
    init         Initialize the environment with default settings
    run          Run a lesson configuration

🔰 Init Command

Generate template files and default configuration:

sabbath-school-reproducer init

This will create:

• A default config.yaml file
• Language files for all supported languages in the languages directory
• A color theme file in the themes directory

▶️ Run Command

Process a configuration file and generate PDF:

sabbath-school-reproducer run config.yaml [options]

Options:

• --debug - Enable debug mode with verbose logging
• --debug-html-only - Only generate debug HTML without PDF
• --quiet-deps - Silence debug messages from dependencies
• -y, --yes - Answer yes to all prompts (force overwrite)

⚙️ Configuration Options

Create a YAML configuration file with the following options:

# Target output options
year: 2025              # Year for generated lessons
quarter: q2             # Quarter (q1, q2, q3, q4)
language: en            # Language code (en, sw, luo)

# File paths
input_file: ./combined_lessons_2025_q2_en_1_null.md   # Path for intermediate markdown file
output_file: ./output/sabbath_school_lesson_2025_q2_en.pdf  # Final PDF path

# Optional cover SVG files
front_cover_svg: ./assets/front_cover.svg   # Custom front cover
back_cover_svg: ./assets/back_cover.svg     # Custom back cover

# Color theme
color_theme_path: ./themes/burgundy.yaml    # Custom color theme

# Language configuration
language_config_path: ./languages/en.yaml   # Language-specific translations

# Reproduction options
reproduce:
  # Original content to adapt
  year: 1905            # Historical year to source from
  quarter: q2           # Historical quarter to source from
  
  # Lesson selection
  start_lesson: 1       # First lesson to include (starting from 1)
  stop_lesson: 13       # Last lesson to include (or null for all)
  
  # New date assignment
  quarter_start_date: 2025-04-01  # First lesson date (YYYY-MM-DD)

# PDF metadata
title: Sabbath School Lessons      # Title for the lesson quarterly
subtitle: Quarter 2, 2025          # Subtitle
publisher: Gospel Sounders         # Publisher name

🔄 Reproduction Mode

The reproduction feature allows you to adapt historical Sabbath School lessons for modern use:

1. Source lessons from a specific historical year and quarter
2. Start from any lesson number (e.g., lesson 5)
3. Set a limit for the number of lessons to include
4. Apply modern dates starting from a specified date
5. Generate a PDF that uses current dates while attributing the source material

Example reproduction configuration:

reproduce:
  year: 1888            # Source from 1888
  quarter: q3           # Third quarter
  start_lesson: 3       # Start from lesson 3
  stop_lesson: 10       # Include up to lesson 10
  quarter_start_date: 2025-04-01  # Use dates starting April 1, 2025

🌐 Multi-language Support

The tool provides comprehensive support for multiple languages:

Supported Languages

• English (en)
• Swahili (sw)
• Luo (luo)

Language Configuration

The language configuration files are generated in the languages directory when you run the init command. You can customize translations by editing these files:

# Language configuration for sw (Swahili)
# This file contains language-specific translations

# Basic terms
notes: 'MAELEZO'  # Used for section headers and headings
note: 'ELEZO'     # Used for single-note sections
questions: 'MASWALI'  # Questions section header
answer_prefix: 'Jibu'  # Prefix for answers in questions
lesson: 'SOMO'  # Used for lesson titles

# Cover page terms
sabbath_school: 'SHULE YA SABATO'  # Main title on cover page
lessons: 'MASOMO'  # Secondary title on cover page
adapted_from: 'Imetoholewa kutoka'  # Text used in "Adapted from X" on cover
from_text: 'kutoka'  # Text used in "from X" in titles

# Quarter names (used in headings and footers)
quarter_names:
  q1: 'ROBO YA KWANZA'
  q2: 'ROBO YA PILI'
  q3: 'ROBO YA TATU'
  q4: 'ROBO YA NNE'

# Quarter month ranges (used in cover pages)
quarter_months:
  q1: 'Januari - Machi'
  q2: 'Aprili - Juni'
  q3: 'Julai - Septemba'
  q4: 'Oktoba - Desemba'

# Table of contents translations
table_of_contents: 'YALIYOMO'
lesson_column: 'Somo'
title_column: 'Kichwa'
date_column: 'Tarehe'
page_column: 'Ukurasa'

# Month names for date formatting
month_names:
  - 'Januari'
  - 'Februari'
  # ... other months

# Date format template
date_format_template: '{day} {month}, {year}'

Using Different Languages

To generate lessons in a specific language:

1. Set the language field in your config.yaml file (e.g., language: sw for Swahili)
2. Ensure the corresponding language file exists (e.g., languages/sw.yaml)
3. Run the tool with your configuration

The tool will automatically:

• Use the correct language when downloading lessons
• Apply language-specific formatting to dates
• Use translated text for all UI elements and headers
• Format the cover page with proper translations

🔍 Advanced Usage

🐞 Debug Mode

Run with debug output for more detailed information:

sabbath-school-reproducer run config.yaml --debug

🌐 Debug HTML Only

Generate only the debug HTML without PDF generation:

sabbath-school-reproducer run config.yaml --debug-html-only

⚡ Force Overwrite

Skip confirmation prompts when overwriting existing files:

sabbath-school-reproducer run config.yaml -y

🎨 Custom CSS

You can customize the PDF styling by modifying the CSS in your project:

# In css_styles.py
CSS_TEMPLATE = """
/* Your custom CSS here */
"""

📚 Documentation

The project documentation is available at https://sabbathschool.github.io/sabbath-school-reproducer/.

To build the documentation locally:

# Navigate to docs directory
cd docs

# Build the documentation
make html

# View the documentation
# Open docs/_build/html/index.html in your browser

👨‍💻 Development

🔢 Version Control

The project includes an automated version checker that increments the version number when building:

./build.sh

🧪 Testing

Run tests with:

pytest tests/

📦 Building and Publishing

To build the package:

# Clean and build
./build.sh

To upload to PyPI:

# Upload to PyPI
./upload.sh

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Steps to contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.