Skip to content

repo_guide

This directory serves as the core Python package for repo-guide. It houses the main execution entry points and the entire logical engine responsible for analyzing Git repositories, interacting with Large Language Models (LLMs), compiling structured documentation, and orchestrating MkDocs to build or host the guide.

The files in this directory work together to provide a seamless CLI application:

  • init.py marks this directory as a Python package.
  • main.py serves as the standard execution entry point. When repo-guide is invoked, it imports and runs the command-line interface defined in cli.py.
  • cli.py defines the complete user interface using the click library and implements the primary generator engine, DocGenerator.

Deep Dive into cli.py

The cli.py file contains the user options and the orchestration logic. The system is split into two major parts: the Click CLI command definition (cli()) and the underlying DocGenerator class.

1. Command-Line Configuration

The cli() function defines a extensive set of configuration flags, including:

  • Model Selection: Allows choosing which model to run (defaulting to gemini-3.5-flash).
  • Token Budgeting: Enables limiting costs or execution scopes using --token-budget and --files-token-limit.
  • Workflow Controls: Lets users skip generation (--no-gen), resume where they left off (--resume), or skip serving the local server (--no-serve).
  • Static Builds & Deployment: Features flags for building static documentation sites (--build) and deploying them straight to GitHub Pages (--gh-deploy).

2. The DocGenerator Engine

At the heart of cli.py, DocGenerator implements the full pipeline for auto-generating a repository guide:

  • Repository Analysis: Uses GitPython to identify files tracked in Git and construct absolute online paths to blobs (e.g., GitHub file URLs), ensuring that generated markdown documents link directly back to the original source code.
  • Binary and File Filtering: Evaluates repository files to skip binary components. It can do this either by inspecting Git's built-in file attributes or, if requested, using Google's magika library to detect file types dynamically. It also filters out files that match user-provided ignore patterns.
  • Prompt Construction: Assembles highly structured contextual prompts. For any given directory, DocGenerator packages the relative paths of files, their textual content, and the previously generated README summaries of nested subdirectories. This hierarchical approach allows the LLM to understand both the contents of the current directory and the context of the subdirectories below it.
  • LLM Orchestration: Interfaces with the llm library to prompt models. It implements an exponential backoff routine to elegantly recover from temporary API failures or rate limits.
  • Token Counting: Uses tiktoken to encode file contents and verify compliance with budget restrictions. This prevents users from unexpectedly exhausting large numbers of tokens on dense directories.
  • MkDocs & Ecosystem Integration: Programmatically writes the MkDocs configuration (mkdocs.yml), sets up local hosting threads via python's subprocess and threading libraries, and sets up a customized Python hook to safely sanitize generated HTML output using bleach.