codeannex 0.2.0__tar.gz → 0.3.0__tar.gz

codeannex-0.3.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: codeannex
+Version: 0.3.0
+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 — with syntax highlighting, a hierarchical table of contents, image rendering, and intelligent font discovery.
+
+## 🚀 Key Features
+
+- **Interactive Wizard 2.0** — Organized by sections (Project, Style, Typography, Layout, Filters) with smart defaults and explicit (Y/n) prompts.
+- **Git Integration & Version Tracking** — Automatically detects Repository URL, Branch, and **Commit SHA**. Supports subdirectories by intelligently ignoring Git metadata if not at the root.
+- **Subdirectories First** — Improved document organization by listing subdirectories and their contents before root files.
+- **Flexible File Filtering** — Multi-pattern include and exclude glob filters (e.g., `--include "src/*" --exclude "tests/*"`).
+- **Intelligent Font Discovery** — Automatically finds fonts from your system (Windows, Linux, macOS) or custom paths via `--font-path`.
+- **Fully Customizable UI** — Control everything: paper size (mm), margins (cm), colors (HEX), and font sizes.
+- **Hierarchical Summary** — Real tree-structured Table of Contents with increasing page numbers and terminal-like connection lines.
+- **Professional Design** — High-contrast line numbers, clean cover page, and smart contrast (auto-switching text between black/white based on accent brightness).
+
+## 🛠 Installation
+
+The recommended way to install **codeannex** is via [pipx](https://github.com/pypa/pipx), which installs the tool in an isolated environment:
+
+```bash
+pipx install codeannex
+```
+
+For full SVG support (required for crisp line numbers and SVG image rendering):
+
+```bash
+pipx install "codeannex[svg]"
+```
+
+*Alternatively, you can use standard pip:* `pip install codeannex`
+
+## 📖 Usage
+
+### Interactive Mode (Wizard)
+Simply run without arguments to start the step-by-step 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
+```
+
+## ⚙️ 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 Name: ").
+
+### 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 and summary icons.
+- `--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.
+
+## 🧪 Testing
+
+```bash
+PYTHONPATH=. pytest
+```
+
+## 📄 License
+
+MIT

codeannex-0.3.0/README.md

@@ -0,0 +1,81 @@
+# 📂 codeannex
+
+Generates a professional PDF annex from a project's source code — with syntax highlighting, a hierarchical table of contents, image rendering, and intelligent font discovery.
+
+## 🚀 Key Features
+
+- **Interactive Wizard 2.0** — Organized by sections (Project, Style, Typography, Layout, Filters) with smart defaults and explicit (Y/n) prompts.
+- **Git Integration & Version Tracking** — Automatically detects Repository URL, Branch, and **Commit SHA**. Supports subdirectories by intelligently ignoring Git metadata if not at the root.
+- **Subdirectories First** — Improved document organization by listing subdirectories and their contents before root files.
+- **Flexible File Filtering** — Multi-pattern include and exclude glob filters (e.g., `--include "src/*" --exclude "tests/*"`).
+- **Intelligent Font Discovery** — Automatically finds fonts from your system (Windows, Linux, macOS) or custom paths via `--font-path`.
+- **Fully Customizable UI** — Control everything: paper size (mm), margins (cm), colors (HEX), and font sizes.
+- **Hierarchical Summary** — Real tree-structured Table of Contents with increasing page numbers and terminal-like connection lines.
+- **Professional Design** — High-contrast line numbers, clean cover page, and smart contrast (auto-switching text between black/white based on accent brightness).
+
+## 🛠 Installation
+
+The recommended way to install **codeannex** is via [pipx](https://github.com/pypa/pipx), which installs the tool in an isolated environment:
+
+```bash
+pipx install codeannex
+```
+
+For full SVG support (required for crisp line numbers and SVG image rendering):
+
+```bash
+pipx install "codeannex[svg]"
+```
+
+*Alternatively, you can use standard pip:* `pip install codeannex`
+
+## 📖 Usage
+
+### Interactive Mode (Wizard)
+Simply run without arguments to start the step-by-step 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
+```
+
+## ⚙️ 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 Name: ").
+
+### 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 and summary icons.
+- `--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.
+
+## 🧪 Testing
+
+```bash
+PYTHONPATH=. pytest
+```
+
+## 📄 License
+
+MIT

codeannex-0.3.0/codeannex/__main__.py

@@ -0,0 +1,136 @@
+import io
+import os
+import sys
+from pathlib import Path
+
+from .core.config import PDFConfig
+from .core.pdf_builder import ModernAnnexPDF
+from .io.file_utils import get_project_files, classify_file, sort_files
+from .io.git_utils import get_git_info
+from .renderer.fonts import init_sprites, register_best_font, register_emoji_font, auto_register_font, ADDITIONAL_SEARCH_PATHS
+from .interface.cli import parse_args, run_interactive_wizard
+from reportlab.lib.units import cm
+
+
+def check_emoji_font_style():
+    emoji_font = register_emoji_font()
+    if emoji_font:
+        print(f"✅ Emoji font registered: {emoji_font}")
+        print("💡 Tip: Install Google Noto fonts for authentic Google emoji style")
+    else:
+        print("⚠️  No emoji font found - emojis may not render correctly")
+    return emoji_font
+
+
+def main():
+    args, unknown = parse_args()
+    is_interactive = len(sys.argv) <= 2 and not args.no_input
+    if is_interactive: run_interactive_wizard(args)
+
+    # Register additional search paths first
+    if args.font_path:
+        ADDITIONAL_SEARCH_PATHS.extend(args.font_path)
+
+    if args.normal_font:   args.normal_font   = auto_register_font(args.normal_font, required=True)
+    if args.bold_font:     args.bold_font     = auto_register_font(args.bold_font, required=True)
+    if args.title_font:    args.title_font    = auto_register_font(args.title_font, required=True)
+    if args.subtitle_font: args.subtitle_font = auto_register_font(args.subtitle_font, required=True)
+    if args.mono_font:     args.mono_font     = auto_register_font(args.mono_font, required=True)
+    if args.emoji_font:    args.emoji_font    = auto_register_font(args.emoji_font, required=True)
+
+    if unknown:
+        for u in unknown:
+            if u.startswith("-"): print(f"⚠️  Warning: Unrecognized argument ignored: {u}")
+
+    if args.check_emoji_font:
+        check_emoji_font_style()
+        return
+
+    root, output = Path(args.dir).resolve(), args.output or f"{Path(args.dir).resolve().name}_anexo_codigo.pdf"
+    use_git = not args.no_git
+    git_url, git_branch, git_sha = get_git_info(root, use_git=use_git)
+    repo_url, branch_name = args.repo_url or git_url, args.branch or git_branch
+
+    mono_font, is_ttf, ttf_path = register_best_font()
+    emoji_font = register_emoji_font(error_on_missing=not args.emoji_description)
+    init_sprites(is_ttf, ttf_path)
+
+    def get_margin(spec, general, default):
+        if spec is not None: return spec * cm
+        if general is not None: return general * cm
+        return default
+
+    from reportlab.lib.units import mm
+    config = PDFConfig(
+        project_name=args.name or root.name,
+        margin_left=get_margin(args.margin_left, args.margin, PDFConfig().margin_left),
+        margin_right=get_margin(args.margin_right, args.margin, PDFConfig().margin_right),
+        margin_top=get_margin(args.margin_top, args.margin, PDFConfig().margin_top),
+        margin_bottom=get_margin(args.margin_bottom, args.margin, PDFConfig().margin_bottom),
+        page_width=args.page_width * mm if args.page_width else PDFConfig().page_width,
+        page_height=args.page_height * mm if args.page_height else PDFConfig().page_height,
+        start_page_num=args.start_page,
+        show_project_name=args.show_project,
+        normal_font=args.normal_font or PDFConfig().normal_font,
+        bold_font=args.bold_font or PDFConfig().bold_font,
+        mono_font=args.mono_font or mono_font,
+        emoji_font=args.emoji_font or emoji_font,
+        emoji_description=args.emoji_description,
+        repo_url=repo_url,
+        branch_name=branch_name,
+        commit_sha=git_sha,
+        page_number_size=args.page_number_size,
+        title_font=args.title_font,
+        title_size=args.title_size,
+        title_color=args.title_color,
+        subtitle_font=args.subtitle_font,
+        subtitle_size=args.subtitle_size,
+        subtitle_color=args.subtitle_color,
+        normal_text_size=args.normal_size,
+        normal_text_color=args.normal_color,
+        page_number_format=args.page_number_format,
+        show_page_numbers=not args.no_page_numbers,
+        cover_title=args.cover_title,
+        primary_color=args.primary_color,
+        cover_subtitle=args.cover_subtitle,
+        summary_title=args.summary_title,
+        repo_label=args.repo_label,
+        project_label=args.project_label,
+        file_part_format=args.file_part_format,
+        code_font_size=args.code_size,
+        code_bg_color=args.code_bg,
+        page_bg_color=args.page_bg_color,
+    )
+
+    all_files = sort_files(get_project_files(root, includes=args.include, excludes=args.exclude, use_git=use_git), root)
+    included = []
+    from .core.config import IMAGE_EXTENSIONS, BINARY_EXTENSIONS
+    script_path, output_path = Path(__file__).resolve(), Path(output).resolve()
+
+    for fp in all_files:
+        try:
+            if fp.resolve() in (script_path, output_path): continue
+        except: pass
+        if not fp.is_file(): continue
+        ext = fp.suffix.lower()
+        if ext == ".svg": included += [(fp, "image"), (fp, "text")]
+        elif ext in IMAGE_EXTENSIONS: included.append((fp, "image"))
+        elif ext in BINARY_EXTENSIONS: continue
+        elif classify_file(fp) == "text": included.append((fp, "text"))
+
+    if not included:
+        print("❌ No compatible files found."); return
+
+    print(f"🧮 Step 1/2: Simulating layout of {len(included)} files...")
+    pdf_sim = ModernAnnexPDF(io.BytesIO(), root, mono_font, emoji_font, config)
+    pdf_sim.is_simulation = True
+    pdf_sim.build(included)
+
+    print("🚀 Step 2/2: Generating the final document...")
+    pdf_final = ModernAnnexPDF(output, root, mono_font, emoji_font, config)
+    pdf_final.summary_data = pdf_sim.summary_data
+    pdf_final.build(included)
+    print(f"✅ Success! Saved to: {output}")
+
+if __name__ == "__main__":
+    main()

{codeannex-0.2.0/codeannex → codeannex-0.3.0/codeannex/core}/config.py

@@ -29,64 +29,52 @@ COLOR_ACCENT    = colors.HexColor("#89b4fa")
 NORMAL_FONT = "Helvetica"
 BOLD_FONT   = "Helvetica-Bold"
 
-# ── Supported image extensions ───────────────
 IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".ico", ".gif", ".webp", ".bmp", ".svg"}
-
-# ── Binary extensions to ignore quickly ──────
-BINARY_EXTENSIONS = {".pdf", ".pyc", ".pyo", ".exe", ".dll", ".so", ".dylib",
-                     ".zip", ".tar", ".gz", ".rar", ".7z", ".jar", ".whl",
-                     ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx"}
-
+BINARY_EXTENSIONS = {".pdf", ".pyc", ".pyo", ".exe", ".dll", ".so", ".dylib", ".zip", ".tar", ".gz", ".rar", ".7z", ".jar", ".whl"}
 
 @dataclass
 class PDFConfig:
-    """PDF configuration for code annex."""
     project_name: str | None = None
     margin_left: float = _DEFAULT_MARGIN_LEFT
     margin_right: float = _DEFAULT_MARGIN_RIGHT
     margin_top: float = _DEFAULT_MARGIN_TOP
     margin_bottom: float = _DEFAULT_MARGIN_BOTTOM
+    page_width: float = PAGE_W
+    page_height: float = PAGE_H
     start_page_num: int = 1
     show_project_name: bool = False
     normal_font: str = NORMAL_FONT
     bold_font: str = BOLD_FONT
-    mono_font: str | None = None  # Will be set by register_best_font
-    emoji_font: str | None = None  # Will be set by register_emoji_font
-    emoji_description: bool = False  # Print descriptions instead of emojis
-    repo_url: str | None = None  # URL of the repository for the cover page
-    page_number_size: int = 8  # Font size for page numbers
+    mono_font: str | None = None
+    emoji_font: str | None = None
+    emoji_description: bool = False
+    repo_url: str | None = None
+    branch_name: str | None = None
+    commit_sha: str | None = None
+    page_number_size: int = 8
 
-    # Customization fields
     title_font: str | None = None
     title_size: int = 28
     title_color: str = "#1e1e2e"
     subtitle_font: str | None = None
     subtitle_size: int = 18
-    subtitle_color: str | None = None # Defaults to title_color
+    subtitle_color: str | None = None
     normal_text_size: int = 10
-    normal_text_color: str = "#4c4f69" # Default COLOR_TEXT_MAIN
-    page_number_format: str = "{n}" # e.g. "Anexo I - {n}" or just "{n}"
+    normal_text_color: str = "#4c4f69"
+    page_number_format: str = "{n}"
     show_page_numbers: bool = True
     cover_title: str = "TECHNICAL ANNEX"
     cover_subtitle: str = "Source Code Documentation"
-    primary_color: str = "#1e66f5" # Professional dark blue
+    primary_color: str = "#1e66f5"
     
-    # Code style
     code_font_size: int = CODE_FONT_SIZE
-    code_bg_color: str = "#1e1e2e" # Default COLOR_CODE_BG
-    page_bg_color: str = "#ffffff" # Default COLOR_PAGE_BG
+    code_bg_color: str = "#1e1e2e"
+    page_bg_color: str = "#ffffff"
     
-    # Labels (Internationalization)
     summary_title: str = "Summary / File Index"
-    repo_label: str = "Repository: "
+    repo_label: str = "Repository Name: "
     project_label: str = "Project: "
-    file_part_format: str = "({current}/{total})" # e.g. "(1/2)"
-    cover_subtitle: str = "Source Code Documentation"
-
-    def get_code_x(self) -> float:
-        """Calculates the initial X position of the code."""
-        return self.margin_left + GUTTER_W
+    file_part_format: str = "(part {current}/{total})"
 
-    def get_code_w(self) -> float:
-        """Calculates the available width for code."""
-        return PAGE_W - self.get_code_x() - self.margin_right
+    def get_code_x(self) -> float: return self.margin_left + GUTTER_W
+    def get_code_w(self) -> float: return self.page_width - self.get_code_x() - self.margin_right