tutorial-any-repo

name	tutorial-any-repo
description	Automatically generate a file-by-file code tutorial website for any repository. Explores codebase structure, creates TODO tracking, launches parallel agent teams to write docs, self-reviews, and deploys to GitHub Pages. Use when user says "write a tutorial for this project", "explain this codebase", "generate code docs", etc.
argument-hint	[target_dir] [language] — target directory (default: cwd) and language (default: English)

Universal Repository Tutorial Generator

You are a professional code tutorial generation system. Your task is to generate file-by-file detailed code explanation tutorials for a given repository and deploy them as a static website.

Input Parameters

• Target directory: $ARGUMENTS[0] (defaults to current working directory)
• Language: $ARGUMENTS[1] (defaults to English)

If no arguments are provided, use the current working directory and English.

---

Execution Pipeline

Execute the following 6 phases strictly in order. After each phase, update progress via TaskUpdate.

Phase 1: Explore & Plan

1. Explore codebase structure: Launch an Explore-type Agent to thoroughly scan all source files in the target directory (.py, .js, .ts, .go, .rs, .java, etc. — detect project language automatically). Output:

   • Complete file inventory, grouped by directory
   • Module count and total file count
   • Identification of main entry points and core modules

2. Create tutorial/ directory structure: Mirror the source code directory hierarchy under a tutorial/ directory at the project root.

3. Create tutorial/TODO.md: A detailed progress tracking document with the following format:

   # Code Tutorial - Progress Tracker
   > Total: N source files to document
   > Created: YYYY-MM-DD
   
   ## Progress Overview
   | Module | Files | Completed | Status |
   |--------|-------|-----------|--------|
   | module_a | X | 0 | ⏳ Pending |
   ...
   
   ## File List by Module
   ### module_a/
   - [ ] `src/module_a/file1.py` → `tutorial/module_a/file1.md`
   ...
   

   Every source file MUST have a corresponding entry — no omissions allowed.

4. Create Task tracking: Use TaskCreate to create a Task for each major module to track progress.

Phase 2: Write Foundation Documents

Launch Agents in parallel to write:

1. Background Knowledge (tutorial/00_background_knowledge.md):

   • Analyze the project's technical domain (e.g., RL, web framework, compiler, etc.)
   • Write beginner-friendly introduction to the domain with core concept explanations
   • Include ASCII diagrams showing system architecture
   • Target audience: readers with zero domain knowledge

2. Reading Guide (tutorial/00_reading_guide.md):

   • Three reading paths: Quick Start (~2 hours), Complete Learning, Topic-based
   • Recommended module reading order with rationale
   • Complete document index with links

Phase 3: Parallel Module Documentation

Core principle: maximize parallelism. Group modules by size and launch multiple Agents simultaneously:

• Small modules (<10 files): one Agent per module
• Medium modules (10-30 files): one Agent per module
• Large modules (>30 files): split across multiple Agents

Agent instruction template:

Write detailed code explanation docs for the [module_name] module of [project_name],
targeting readers with no prior knowledge. Write in [language].

First use Glob to find all source files under [module_path] (recursively),
then read each file and write a tutorial document.

Each source file gets a corresponding markdown tutorial doc, written to [tutorial_target_dir].

Each tutorial document format:
- Title: `filename.ext` — short description
- File Overview: what this file does and its role in the project
- Key Code Walkthrough: paste key code snippets and explain them step by step (use fenced code blocks)
- Core Classes/Functions: table listing each class/function and its purpose
- Relationship to Other Modules: how this file connects to the rest of the codebase
- Summary

Also write a module overview: [tutorial_target_dir]/index.md with an architecture diagram (ASCII art).

For __init__ or similar boilerplate files, keep the explanation brief.
Always Read source code first, then Write tutorial docs.

After each Agent completes, immediately update TaskUpdate and TODO.md progress.

Phase 4: Self-Review

Launch a Review Agent to check:

1. Completeness: Glob all generated .md files, cross-reference with TODO.md to confirm no missing docs
2. Quality spot-check: Sample 1-2 docs from each module (at least 10 total), verify:
   • Has title, has code snippets, has class/function listing
   • Content is in the target language, non-empty
   • Content is coherent (no garbled or duplicated text)
3. Fix: Repair any issues found, create any missing files

Phase 5: Build Website

1. Install dependencies:

   pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin jieba
   

2. Create mkdocs.yml (project root):

   site_name: "[Project Name] Code Tutorial"
   docs_dir: "tutorial"
   site_dir: "site"
   theme:
     name: material
     language: en  # adjust based on target language (zh for Chinese, etc.)
     palette:
       - scheme: default
         primary: indigo
         toggle: {icon: material/brightness-7, name: Switch to dark mode}
       - scheme: slate
         primary: indigo
         toggle: {icon: material/brightness-4, name: Switch to light mode}
     features:
       - navigation.instant
       - navigation.sections
       - navigation.expand
       - navigation.top
       - navigation.indexes
       - search.suggest
       - search.highlight
       - content.code.copy
       - toc.follow
   plugins:
     - search:
         lang: [en]  # add 'zh' for Chinese, etc.
         separator: '[\s\u200b\-]'
     - awesome-pages
   markdown_extensions:
     - tables
     - pymdownx.highlight: {anchor_linenums: true}
     - pymdownx.superfences
     - pymdownx.arithmatex: {generic: true}
     - admonition
     - pymdownx.details
     - toc: {permalink: true}
   extra_javascript:
     - javascripts/mathjax.js
     - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
   

   For Chinese language, add jieba for search segmentation and set lang: [zh, en].

3. Create tutorial/index.md homepage with the following sections:

   • Project introduction
   • Architecture overview diagram (ASCII art): Show the project's overall architecture — major components, their relationships, and data flow between them. This gives readers an immediate big-picture understanding.
   • Main workflow/pipeline diagram (ASCII art): Show the primary execution flow step by step (e.g., for a training framework: data input → processing stages → output; for a web framework: request → middleware → handler → response). Number each step.
   • Code-to-flow mapping table: A table mapping each workflow step to its corresponding source file and tutorial document, so readers can jump from the diagram directly to the relevant code.
   • Module index table with doc counts and descriptions
   • Quick start reading links

4. Create tutorial/.pages for navigation ordering

5. Create tutorial/javascripts/mathjax.js for MathJax configuration:

   window.MathJax = {
     tex: {
       inlineMath: [["\\(", "\\)"]],
       displayMath: [["\\[", "\\]"]],
       processEscapes: true,
       processEnvironments: true
     },
     options: {
       ignoreHtmlClass: ".*|",
       processHtmlClass: "arithmatex"
     }
   };
   document$.subscribe(() => { MathJax.typesetPromise() })
   

6. Ensure every subdirectory has index.md (rename from README.md if needed, fix internal links)

7. Add site/ to .gitignore

8. Local build test: Run mkdocs build and confirm no critical errors

Phase 6: Deploy to GitHub Pages

1. Detect GitHub info:

   gh auth status
   git remote -v
   

2. Ensure a pushable remote exists:

   • If origin is the user's own repo: use origin directly
   • If origin is someone else's repo: check for existing fork, or gh repo fork
   • Add fork as remote (e.g., myfork)

3. Update site_url in mkdocs.yml to the actual deployment URL

4. Deploy:

   mkdocs gh-deploy --remote-name <remote> --force
   git push <remote> main
   

5. Enable GitHub Pages:

   gh api repos/<owner>/<repo>/pages -X PUT \
     -f "build_type=legacy" -f "source[branch]=gh-pages" -f "source[path]=/"
   

6. Create GitHub Actions workflow (.github/workflows/tutorial-docs.yml) for automatic redeployment on push

7. Output the final URL to the user

---

Core Principles

1. Never stop early: Do not stop until every single source file has a corresponding tutorial document. If you stop before full coverage, the tutorial is incomplete and useless.
2. Maximize parallelism: Launch as many background Agents as possible using run_in_background: true. This is the key to finishing large codebases in reasonable time.
3. Transparent progress: Update TODO.md and Task status after each Agent completes, so the user always knows current progress.
4. Incremental commits: Git commit after each major phase to save progress and allow recovery.
5. Self-review: Always review your own output before declaring done. Check for missing files, empty docs, and quality issues.
6. Consistent title format: All doc titles must follow `filename.ext` — short description format for clean sidebar navigation.
7. LaTeX for math: If content involves mathematical formulas, use LaTeX rendering (\(...\) inline, $$...$$ display), never plain-text code blocks.
8. Architecture & flow diagrams on homepage: The tutorial homepage (index.md) MUST include an architecture overview diagram and a main workflow diagram (both as ASCII art), plus a code-to-flow mapping table. Readers need to build a global mental model before diving into individual files.