CodeVetter · Repo Unpack · Data flow
krahets/hello-algo
Data flow is a static publishing pipeline rather than a runtime system. Author inputs are markdown pages, PNG frame assets, and code files; these flow through a staged build/ directory into per-locale mkdocs builds, producing one static site/ tree served over HTTP. Code samples move by manual transcription: authors write codes/<lang>/chapter_* files, then copy excerpts into the docs' tabbed blocks and into URL-encoded PythonTutor links. At view time the browser pulls third-party resources (MathJax CDN, giscus.app, pythontutor.com, contrib.rocks) — the repo itself serves only static files.
- Build pipeline: Dockerfile copies overrides→build/overrides and docs→build/docs, runs 'mkdocs build -f mkdocs.yml' producing site/, then repeats the copy+build for each locale where locale mkdocs.yml sets docs_dir=../build/<locale>/docs and site_dir=../site/<locale> — all locales land in one /hello-algo/site tree.
- Locale configs are derived, not duplicated: en/mkdocs.yml (and zh-hant/ja/ru equivalents) start with 'INHERIT: ../mkdocs.yml' and only override identity fields (site_name, site_url, docs_dir, site_dir, theme.language, nav), so structural changes to the root config propagate to all locales.
- Code-to-docs flow is manual transcription: docs pages contain fenced copies of the sample code inside === 'Lang' tabs (e.g. array.md's Python block mirrors array.py's logic), so the docs and codes/ trees are independent artifacts that must be kept in sync by contributors.
- PythonTutor flow: each function's source is URL-encoded into a pythontutor.com/render.html#code=... URL with parameters like curInstr, mode=display, py=311; the URLs are stored both inline in '??? pythontutor' admonitions and as standalone records in codes/pythontutor/chapter_*/*.md.
- Animation flow: authors produce ordered PNG frames in <page>.assets/ and reference them as === '<N>' tabs; at view time animation_player.js detects all-numeric-label tabbed sets via isAnimationSet(), wraps them in controllers with prev/next/play buttons, and auto-advances the checked radio input on a 1500ms interval.
- Comment data flow: page.meta.comments flag → comments.html emits a localized prompt + giscus.app script tag with repo/category IDs → giscus maps the page pathname to a GitHub Discussion → theme changes are pushed back via postMessage to the giscus iframe.
- CI data flow: push/PR events filtered on paths 'codes/<lang>/**' and 'en/codes/<lang>/**' trigger the matching workflow; the job checks out the repo, sets up the toolchain, then builds or executes every sample in that directory, failing the run on any compile/runtime error.
- Python execution harness: test_all.py globs 'chapter_*/*.py', subprocess.Popens 'python <file>' for each with PYTHONIOENCODING=utf-8, collects stderr per file, and raises RuntimeError aggregating all stderr if any exit code is non-zero — 'Tested N files / Found exception in M files' is the only output.
- JavaScript execution harness: codes/javascript/test_all.js uses Deno APIs (expandGlob 'chapter_*/*.js', Deno.Command 'node') to spawn every sample under node, awaiting all statuses — the CI workflow invokes it via 'deno run -A test_all.js'.
- Helper-module data flow: chapter samples import shared structures (e.g. 'use hello_algo_rust::include::print_util' in array.rs, 'from modules import *' style in Python) so TreeNode/ListNode/Vertex construction and printing flow through one module per language, keeping sample files focused on the algorithm.
- Rendered pages pull external assets at view time: MathJax from cdnjs.cloudflare.com, giscus client from giscus.app, contributor image from contrib.rocks, PythonTutor frames from pythontutor.com — declared in mkdocs.yml extra_javascript, comments.html, docs/index.html, and ??? pythontutor blocks respectively.