Skip to content

Commit e445908

Browse files
travisjneumanclaude
travisjneuman
and
claude
committed
docs: add --help to tool scripts and create tools/README.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent a9cca9f commit e445908

5 files changed

Lines changed: 176 additions & 16 deletions

File tree

‎tools/README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Curriculum Tools
2+
3+
Scripts that support the learn.python curriculum. Learner tools help you track progress and find your starting point. Maintainer tools keep the curriculum's cross-references and navigation links consistent.
4+
5+
**Prerequisites:** Python 3.11+, pytest (for `grade.py`), ripgrep (`rg`) and bash (for shell-based checks).
6+
7+
---
8+
9+
## For Learners
10+
11+
### grade.py
12+
13+
Run project tests and get friendly, educational feedback — not just pass/fail.
14+
15+
```bash
16+
python tools/grade.py projects/level-0/01-terminal-hello-lab/
17+
python tools/grade.py --level 0
18+
python tools/grade.py --level 0 --summary
19+
python tools/grade.py --modules
20+
python tools/grade.py --all
21+
python tools/grade.py --all -v # verbose: show failure details
22+
```
23+
24+
Runs pytest on the target project(s), counts passed/failed tests, prints a score bar, and links failures to concept docs for review. Uses `tools/grading_config.json` for concept hints.
25+
26+
### diagnose.py
27+
28+
Interactive diagnostic assessments that help you find where to start or identify knowledge gaps.
29+
30+
```bash
31+
python tools/diagnose.py # list available diagnostics
32+
python tools/diagnose.py gate-a # setup readiness check
33+
python tools/diagnose.py level-0 # terminal/IO readiness
34+
python tools/diagnose.py level-1 # functions readiness
35+
```
36+
37+
Loads question banks from `tools/diagnostics/`, runs a quiz in the terminal, scores by topic, and recommends whether to skip ahead, start the level, or review first.
38+
39+
### progress.py
40+
41+
Visual dashboard that scans the repo to show learning progress based on actual work done.
42+
43+
```bash
44+
python tools/progress.py # overall progress bars
45+
python tools/progress.py --detail level-0 # per-project breakdown
46+
python tools/progress.py --streak # 30-day commit heatmap
47+
python tools/progress.py --next # what to work on next
48+
```
49+
50+
Detects code files, test files, and notes in each project directory. The streak view reads git history to show your practice consistency.
51+
52+
### generate_personalized_study_plan.py
53+
54+
Generates a markdown study plan tailored to your experience, schedule, and goals.
55+
56+
```bash
57+
python tools/generate_personalized_study_plan.py \
58+
--hours-per-week 10 --learning-mode hybrid \
59+
--confidence medium --experience beginner --goal full_stack
60+
61+
python tools/generate_personalized_study_plan.py \
62+
--hours-per-week 5 --learning-mode play \
63+
--confidence low --experience zero --goal automation \
64+
--output my-plan.md
65+
```
66+
67+
All arguments are required except `--stuck-area` (defaults to `none`) and `--output` (prints to stdout if omitted). The output includes a starting doc, project ladder entry point, weekly session pattern, priority doc chain, and remediation actions.
68+
69+
---
70+
71+
## For Maintainers
72+
73+
### add_crossrefs.py
74+
75+
Adds "Related Concepts" sections to project READMEs and "Practice This" sections to concept docs.
76+
77+
```bash
78+
python tools/add_crossrefs.py
79+
```
80+
81+
Idempotent — detects existing sections and skips them. Uses keyword matching and level/module mappings to determine which concepts are relevant to each project. Also links to quizzes, flashcards, and coding challenges where available.
82+
83+
### rebuild_navigation.py
84+
85+
Rebuilds the complete prev/home/next navigation chain across every curriculum document.
86+
87+
```bash
88+
python tools/rebuild_navigation.py
89+
```
90+
91+
Strips old navigation sections and writes fresh nav tables to all 50+ root/curriculum docs, 175 project READMEs, and 10 elite-track READMEs. Run this after adding, removing, or reordering documents.
92+
93+
### Shell-based CI checks
94+
95+
These scripts validate structural contracts across the curriculum. They are called individually or as a suite.
96+
97+
#### run_all_curriculum_checks.sh
98+
99+
Runs all 9 contract checks in sequence. Pass `--full` to include extended smoke tests.
100+
101+
```bash
102+
bash tools/run_all_curriculum_checks.sh
103+
bash tools/run_all_curriculum_checks.sh --full
104+
```
105+
106+
#### Individual checks
107+
108+
| Script | What it verifies |
109+
|--------|-----------------|
110+
| `check_markdown_links.sh` | All relative markdown links (`./path.md`) resolve to existing files |
111+
| `check_root_doc_contract.sh` | Root docs (00-15) and curriculum docs (16-50) have required sections, home links, next-chain links, and source sections |
112+
| `check_level_index_contract.sh` | Each level index (level-0 through level-10) lists exactly 15 projects with valid links and next/return navigation |
113+
| `check_project_readme_contract.sh` | All 165 project READMEs have required headings (Run, Expected output, Alter/Break/Fix, Mastery check, etc.) and portable path notes |
114+
| `check_project_python_comment_contract.sh` | All 165 `project.py` files start with a docstring and have minimum comment density; same for test files |
115+
| `check_portable_paths.sh` | No markdown file contains user-specific absolute paths (`/Users/...` or `C:\Users\...`) |
116+
| `check_elite_track_contract.sh` | Elite track projects have all required files (`project.py`, `tests/`, `data/`) and README headings |
117+
118+
```bash
119+
bash tools/check_markdown_links.sh
120+
bash tools/check_portable_paths.sh
121+
# etc.
122+
```
123+
124+
All checks exit 0 on success and non-zero on failure, making them suitable for CI pipelines.

‎tools/add_crossrefs.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -405,4 +405,12 @@ def main():
405405

406406

407407
if __name__ == "__main__":
408+
import argparse
409+
410+
parser = argparse.ArgumentParser(
411+
description="Cross-reference linker. Adds 'Related Concepts' sections to "
412+
"project READMEs and 'Practice This' sections to concept docs. "
413+
"Idempotent — skips files that already have cross-references.",
414+
)
415+
parser.parse_args()
408416
main()

‎tools/generate_personalized_study_plan.py‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
"""Generate a personalized study plan from learner constraints.
22
3-
This script intentionally keeps logic explicit and deterministic so learners can
4-
read, modify, and understand every recommendation rule.
3+
Produces a markdown study plan based on experience level, available hours,
4+
learning mode, and goals. The logic is intentionally explicit and deterministic
5+
so learners can read, modify, and understand every recommendation rule.
6+
7+
Usage:
8+
python tools/generate_personalized_study_plan.py \\
9+
--hours-per-week 10 --learning-mode hybrid \\
10+
--confidence medium --experience beginner --goal full_stack
11+
12+
python tools/generate_personalized_study_plan.py \\
13+
--hours-per-week 5 --learning-mode play \\
14+
--confidence low --experience zero --goal automation \\
15+
--output my-plan.md
516
"""
617

718
from __future__ import annotations

‎tools/progress.py‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -333,26 +333,36 @@ def show_next():
333333

334334

335335
def main():
336-
args = sys.argv[1:]
337-
338-
if "--help" in args or "-h" in args:
339-
print(__doc__)
340-
return
341-
342-
if "--streak" in args:
336+
import argparse
337+
338+
parser = argparse.ArgumentParser(
339+
description="Progress dashboard. Scans the repository to show learning "
340+
"progress based on actual work done (files created, tests passing, notes written).",
341+
)
342+
parser.add_argument(
343+
"--detail", type=str, default=None, metavar="LEVEL",
344+
help="show detailed progress for a specific level or module (e.g. level-0)",
345+
)
346+
parser.add_argument(
347+
"--streak", action="store_true",
348+
help="show your practice streak from git commit history",
349+
)
350+
parser.add_argument(
351+
"--next", action="store_true",
352+
help="recommend what to work on next",
353+
)
354+
args = parser.parse_args()
355+
356+
if args.streak:
343357
show_streak()
344358
return
345359

346-
if "--next" in args:
360+
if args.next:
347361
show_next()
348362
return
349363

350-
if "--detail" in args:
351-
idx = args.index("--detail")
352-
if idx + 1 < len(args):
353-
show_detail(args[idx + 1])
354-
else:
355-
print("Usage: python tools/progress.py --detail <level-name>")
364+
if args.detail is not None:
365+
show_detail(args.detail)
356366
return
357367

358368
show_overview()

‎tools/rebuild_navigation.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,4 +353,11 @@ def main():
353353

354354

355355
if __name__ == "__main__":
356+
import argparse
357+
358+
parser = argparse.ArgumentParser(
359+
description="Rebuild complete navigation chain across the entire curriculum. "
360+
"Updates every markdown file with consistent prev/home/next navigation links.",
361+
)
362+
parser.parse_args()
356363
main()

0 commit comments

Comments
 (0)