Commit 0aae7666 authored by Jan Reimes's avatar Jan Reimes
Browse files

docs(readme): update usage instructions and configuration details 

* Remove mise task system mention from features
* Add detailed CLI usage examples for document conversion
* Include environment variable setup for Zamzar and default provider
* Revise development instructions to use uv commands instead of mise
parent e33313c7

README.md

+83 −34
Original line number Diff line number Diff line
@@ -9,7 +9,6 @@ Converts MS Office documents (Word, Excel, Powerpoint) to PDF via API providers/ 
- ✅ **Pytest**: Testing framework with 100% coverage requirement

- ✅ **Ruff**: Fast Python linter and formatter

- ✅ **codespell**: Spell checker for code and documentation

- ✅ **mise Task System**: Advanced task runner with DAG dependency management

- ✅ **Pre-commit Hooks**: Automated code quality checks

- ✅ **Zensical**: Modern documentation with Material Design theme

- ✅ **Dynamic Versioning**: Git-based versioning with uv-dynamic-versioning
@@ -22,60 +21,111 @@ git clone https://github.com/yourusername/pdf-remote-converter.git 
cd pdf-remote-converter



# Install dependencies

mise dev



# Or manually

uv sync --dev

```



## Usage



### CLI: Convert Office Documents to PDF



```bash

# Basic conversion (uses default configured provider)

pdf-remote-converter convert input.docx output.pdf



# Specify a provider explicitly

pdf-remote-converter convert --provider cloudconvert input.xlsx output.pdf

pdf-remote-converter convert --provider adobe input.pptx output.pdf



# Provide API key via command line

pdf-remote-converter convert --api-key YOUR_KEY --provider zamzar input.docx output.pdf



# Force fresh conversion (bypass HTTP cache)

pdf-remote-converter convert --force input.docx output.pdf



# Enable verbose logging for debugging

pdf-remote-converter convert --verbose input.docx output.pdf



# Show help and available options

pdf-remote-converter convert --help

```



### Configuration



All configuration is via environment variables. Set up your credentials:



```bash

# CloudConvert (10 conversions/day free tier)

export CLOUDCONVERT_API_KEY=your_api_key



# Adobe PDF Services (500 transactions/month free tier)

export ADOBE_CLIENT_ID=your_client_id

export ADOBE_CLIENT_SECRET=your_client_secret



# Zamzar (100 credits/month free tier, 1MB max)

export ZAMZAR_API_KEY=your_api_key



# Optional: Default provider (default is cloudconvert)

export PDF_REMOTE_CONVERTER_DEFAULT_PROVIDER=cloudconvert



# Optional: Cache directory (default is ~/.cache/pdf-remote-converter)

export PDF_REMOTE_CONVERTER_CACHE_DIR=~/.cache/pdf-remote-converter

```



Copy `.env.example` to `.env` and fill in your credentials:



```bash

cp .env.example .env

# Edit .env with your API keys

```



### Running Tests



```bash

mise test

# or

uv run pytest

# Run all tests with coverage

uv run pytest tests/ -v --cov=pdf_remote_converter --cov-report=term-missing

```



### Code Quality



```bash

# Run linter

mise lint

# Run linter and type checks

uv run ruff check src/ tests/

uv run ty src/



# Format code

mise format

# Run formatter

uv run ruff format src/ tests/



# Check spelling

mise spell

uv run codespell src/ tests/



# Run all checks

mise all

# Run type checking with ty

uv run ty src/

```



### CLI Commands

### Programmatic Usage (Python Library)



```bash

# Default command

python -m pdf_remote_converter

```python

from pdf_remote_converter import Converter



# Greet someone

python -m pdf_remote_converter greet Alice

# Create converter with default settings

converter = Converter()



# Add numbers

python -m pdf_remote_converter add 5 3

# Convert document

result = converter.convert("input.docx", "output.pdf")



# Show version

python -m pdf_remote_converter --version

```

# Check result

print(f"Converted by: {result.provider}")

print(f"From cache: {result.from_cache}")

print(f"Credits used: {result.credits_used}")



### Environment Variables

# Use specific provider

converter = Converter(provider="adobe")

result = converter.convert("input.xlsx", "output.pdf")



| Variable | Description |

|----------|-------------|

| `PDF_REMOTE_CONVERTER_CACHE` | Enable/disable caching (true/false) |

| `PDF_REMOTE_CONVERTER_OUTPUT_FILE` | Default output file path |

# Provide API key programmatically

converter = Converter(provider="cloudconvert", api_key="your_key")

result = converter.convert("input.pptx", "output.pdf")

```



## Development
@@ -83,7 +133,7 @@ python -m pdf_remote_converter --version 


```bash

# Install all dependencies including dev tools

mise dev

uv sync --dev

```



### Pre-commit Hooks
@@ -98,14 +148,13 @@ pre-commit run --all-files 
### Building Documentation



```bash

mise docs

uv run zensical build

```



## Project Structure



```

pdf-remote-converter/

├── .config/mise/config.toml                # mise tasks/configuration

├── docs/                                   # Zensical documentation

├── src/pdf_remote_converter/

│   ├── __init__.py
@@ -137,7 +186,7 @@ See the [LICENSE](LICENSE) file for details. 
1. Fork the repository

1. Create a feature branch

1. Make your changes

1. Run quality checks: `mise all`

1. Run quality checks: `uv run ruff check src/ tests/ && uv run ruff format src/ tests/ && uv run pytest tests/ -v --cov=pdf_remote_converter --cov-report=term-missing`

1. Submit a pull request



## Support