Metadata-Version: 2.4
Name: codeannex
Version: 0.4.4
Summary: Generates a professional PDF source code annex with Smart Index, Images and Emoji support.
License: MIT
Project-URL: Repository, https://github.com/tanhleno/codeannex
Keywords: pdf,source-code,documentation,annex,reportlab,emoji
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: reportlab>=4.0
Requires-Dist: Pillow>=10.0
Requires-Dist: Pygments>=2.16
Requires-Dist: pdfminer.six>=20231228
Provides-Extra: svg
Requires-Dist: cairosvg>=2.7; extra == "svg"
Requires-Dist: svglib>=1.5; extra == "svg"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 📂 codeannex

Generates a professional PDF annex from a project's source code — featuring syntax highlighting, a hierarchical table of contents, image rendering, and version tracking.

## 🚀 Key Features

- **Interactive Wizard 2.0** — Step-by-step configuration with smart sections (Project, Style, Typography, Layout, Filters) and explicit default prompts.
- **Smart Emoji Support** — Automatic discovery of standard emoji fonts (**Segoe UI Emoji** on Windows, **DejaVu Sans** on Linux).
- **Graceful Emoji Fallback** — If no emoji font is found, it uses official Unicode names (e.g., `[ROCKET]`) for perfect readability.
- **Git Version Tracking** — Automatically detects **Repository URL**, **Branch**, and **Commit SHA**. Smart root detection avoids Git metadata on subdirectories.
- **Smart SVG Rendering** — Files are rendered as both a high-quality image and XML code. Entries are intelligently deduplicated in the summary.
- **Improved Document Structure** — Subdirectories and their contents are listed before root files for better organization.
- **High-Contrast Design** — Redesigned cover page, thickened image frames, and optimized line number legibility.
- **Intelligent Font Discovery** — Automatically finds fonts from your system or custom directories via `--font-path`.
- **Flexible File Filtering** — Multi-pattern include and exclude glob filters (e.g., `--include "src/*" --exclude "tests/*"`).
- **Pro-Level UI** — Control paper size (mm), margins (cm), accent colors (HEX), and font sizes.

## 🛠 Installation

The recommended way to install **codeannex** is via [pipx](https://github.com/pypa/pipx):

```bash
pipx install codeannex
```

For full SVG support (required for crisp line numbers and SVG image rendering):

```bash
pipx install "codeannex[svg]"
```

*Note: For best emoji rendering on Linux, you may want to install `fonts-noto-color-emoji` or `ttf-dejavu`.*

## 📖 Usage

### Interactive Mode (Wizard)
Simply run without arguments to start the configuration:
```bash
python3 -m codeannex
```

### Automation / CI
```bash
python3 -m codeannex . \
  --cover-title "Technical Annex" \
  --primary-color "#0f4761" \
  --code-size 9 \
  --include "src/*" \
  --exclude "*.log" \
  --no-input
```

Default output filename is `{project_name}_code_annex.pdf`.

## ⚙️ Configuration Options

### Git & Metadata
- `--repo-url URL` — Manual repository URL.
- `--branch NAME` — Manual branch name.
- `--no-git` — Force disable Git integration.
- `--repo-label LABEL` — Label for repo (default: "Repository: ").

### File Selection
- `--include PATTERN` — Include glob pattern (can be used multiple times).
- `--exclude PATTERN` — Exclude glob pattern (can be used multiple times).

### Design & Layout
- `--page-width MM` / `--page-height MM` — Custom paper size in mm (default: A4).
- `--margin CM` — General margin (top, bottom, left, right).
- `--primary-color HEX` — Accent color for headers, summary icons, and links.
- `--code-size N` — Font size for code and line numbers.

### Fonts
- `--font-path PATH` — Additional directory to search for `.ttf`/`.otf` files.
- `--title-font` / `--normal-font` / `--mono-font` — System font names.
- `--emoji-font NAME` — Custom font for emojis.
- `--emoji-description` — Force textual descriptions (e.g., `[GRINNING FACE]`) instead of glyphs.

## 🧪 Testing

```bash
PYTHONPATH=. pytest tests --cov=codeannex
```

## 📄 License

MIT
