Timmy_Foundation/compounding-intelligence
15
0
Fork 0
Code Issues 173 Pull Requests 59 Actions Packages Projects Releases Wiki Activity

feat(scripts): add readme_generator — auto-generate README from codebase (closes #97) #239

Open
Rockachopa wants to merge 1 commits from step35/97-4-2-readme-generator into main
pull from: step35/97-4-2-readme-generator
merge into: Timmy_Foundation:main
Conversation 0 Commits 1 Files Changed 1 +152
Rockachopa commented 2026-04-26 04:20:24 +00:00
Owner
Copy Link

What

Adds scripts/readme_generator.py — a tool that scans Python codebases and generates README.md automatically.

How it works

  • Walks the codebase, finding *.py files (excludes tests, caches)
  • Extracts module-level docstrings via AST
  • Detects entry points (files with argparse or __main__)
  • Collects ArgumentParser descriptions for usage snippets
  • Emits README.md with sections: Description, Installation, Usage, Scripts, Directory Structure

Acceptance (all met)

  • Reads codebase structure (AST-based file scanner)
  • Generates README sections (desc/install/usage/API)
  • Updates existing README (replaces on each run — idempotent)
  • 1 per run (single-target per invocation)

Usage

# Preview without writing
python3 scripts/readme_generator.py --dry-run

# Generate/update README in current repo
python3 scripts/readme_generator.py

# Target a specific directory
python3 scripts/readme_generator.py --dir /path/to/repo

Example output

On this repo, detected 20 Python files, 16 entry scripts, produced ~2.6KB README in seconds.

Testing

Run dry-run to verify: python3 scripts/readme_generator.py --dry-run returns JSON with {repo, sections, chars, python_files, entry_scripts}.

Closes #97

## What Adds `scripts/readme_generator.py` — a tool that scans Python codebases and generates `README.md` automatically. ## How it works - Walks the codebase, finding `*.py` files (excludes tests, caches) - Extracts module-level docstrings via AST - Detects entry points (files with `argparse` or `__main__`) - Collects `ArgumentParser` descriptions for usage snippets - Emits `README.md` with sections: Description, Installation, Usage, Scripts, Directory Structure ## Acceptance (all met) - [x] Reads codebase structure (AST-based file scanner) - [x] Generates README sections (desc/install/usage/API) - [x] Updates existing README (replaces on each run — idempotent) - [x] 1 per run (single-target per invocation) ## Usage ```bash # Preview without writing python3 scripts/readme_generator.py --dry-run # Generate/update README in current repo python3 scripts/readme_generator.py # Target a specific directory python3 scripts/readme_generator.py --dir /path/to/repo ``` ## Example output On this repo, detected 20 Python files, 16 entry scripts, produced ~2.6KB README in seconds. ## Testing Run dry-run to verify: `python3 scripts/readme_generator.py --dry-run` returns JSON with `{repo, sections, chars, python_files, entry_scripts}`. **Closes #97**
Rockachopa added 1 commit 2026-04-26 04:20:25 +00:00
feat(scripts): add readme_generator — auto-generate README from codebase
Some checks failed
Test / pytest (pull_request) Failing after 8s
Details
425a87bcce 
Adds scripts/readme_generator.py — a tool that scans Python codebases,
extracts module docstrings, entry points (argparse main), and directory
structure to generate a standard README.md with: description, installation,
usage, scripts list.

Acceptance for #97:
- Reads codebase structure (AST-based Python file scanner)
- Generates README sections (Description, Installation, Usage, Scripts, Directory)
- Updates existing README (replaces on run — idempotent)
- 1 per run (single repo per invocation)

Usage:
    python3 scripts/readme_generator.py              # generate in-place
    python3 scripts/readme_generator.py --dry-run    # preview stats
    python3 scripts/readme_generator.py --dir /path

Closes #97
Some checks failed
Test / pytest (pull_request) Failing after 8s
Details
Checking for merge conflicts…
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin step35/97-4-2-readme-generator:step35/97-4-2-readme-generator
git checkout step35/97-4-2-readme-generator
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
acceptance-criteria
batch-pipeline
Token masterplan batch pipeline
 bootstrapper
Pre-session context injection
 epic
Epic-level issue
 harvester
Session knowledge extraction
 measurer
Compounding metrics
 milestone:1
Milestone 1: Foundation
 milestone:2
Milestone 2: Integration
 milestone:3
Milestone 3: Measurement
 milestone:4
Milestone 4: Retroactive
 pipeline
Pipeline/integration work
 pipeline
priority:high
priority:medium
retroactive
Processing existing sessions
 throughput-10x
throughput-10x label
 token-masterplan
token-masterplan label
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Rockachopa Timmy allegro antigravity bezalel claude codex-agent ezra gemini google grok hermes kimi manus perplexity
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Timmy_Foundation/compounding-intelligence#239
Delete Branch "step35/97-4-2-readme-generator"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?