Skip to content

Add a Python-based tutorials website generator and deploy workflow - #9347

Open
alexreinking wants to merge 4 commits into
mainfrom
alexreinking/new-tutorial-site
Open

Add a Python-based tutorials website generator and deploy workflow#9347
alexreinking wants to merge 4 commits into
mainfrom
alexreinking/new-tutorial-site

Conversation

@alexreinking

@alexreinking alexreinking commented Aug 16, 2026

Copy link
Copy Markdown
Member

Summary

  • Replaces the old two-repo, gdb-only shell pipeline (tutorial/figures/generate_output_snippets.sh + halide.github.com/tutorials/gen_tutorials.sh) with a single in-tree Python tool under tutorial/website/, wired in as an opt-in CMake feature (WITH_TUTORIAL_WEBSITE, off by default, requires WITH_TUTORIALS) with its own install component (Halide_Tutorial) and directory knob (Halide_INSTALL_TUTORIALDIR).
  • The generator drives either GDB or LLDB in batch mode to capture the output of interesting statements (Func::realize(), print_loop_nest(), etc.) directly from the built lesson binaries, highlights the code with Pygments, and renders a dependency-free static site (no JS, no Bootstrap) with collapsible <details> output blocks, inlined figures, and a nav sidebar that groups multi-part lessons (10, 15, 16, 21) under one header.
  • Requires no changes to the lesson .cpp/.sh sources themselves beyond giving the multi-part lessons distinct, descriptive titles (they previously said just "part 1"/"part 2", or in lesson 21's case, were identical) and adding gdb/lldb-friendly compile flags gated behind the new feature.
  • Adds .github/workflows/deploy-docs.yml: builds the Doxygen API docs (WITH_DOCS) and the new tutorials website on release and manual dispatch, then deploys both to halide/halide.github.com using the same GitHub App as the existing LLVM-updater workflows. Manual runs default to a dry run (build + diff only, artifact upload instead of a push) and can target a personal fork via an input to rehearse a real push safely.
image

Test plan

  • Built libHalide + all 27 tutorial lesson binaries locally with -DWITH_TUTORIAL_WEBSITE=ON; ran the generator via LLDB and confirmed real captured output (e.g. HL_DEBUG_CODEGEN trace for lesson 3, print_loop_nest/tracing output for lessons 4/5/8/9/18/19).
  • Confirmed figure embedding, multi-part nav grouping, and the new shell-script lesson (15's lesson_15_generators_usage.sh) all render correctly.
  • cmake --install --component Halide_Tutorial lands files under share/tutorial/.
  • ruff check/ruff format and this repo's check_cmake_style.py/check_cmake_file_lists.py all pass; full pre-commit run --all-files-equivalent hooks pass on every commit.
  • deploy-docs.yml itself hasn't been run in CI yet -- recommend triggering it once via workflow_dispatch with the default dry_run: true (safe, no push) to sanity-check the artifact before relying on it for a real release.

🤖 Generated with Claude Code

alexreinking and others added 3 commits August 16, 2026 02:16
Replaces the old two-repo, gdb-only shell pipeline
(tutorial/figures/generate_output_snippets.sh +
halide.github.com/tutorials/gen_tutorials.sh) with a single in-tree Python
tool under tutorial/website/. It drives either GDB or LLDB in batch mode to
capture the output of interesting statements (Func::realize(),
print_loop_nest(), etc.) directly from the built lesson binaries, highlights
the code with Pygments, and renders a dependency-free static site (no JS,
no Bootstrap) with collapsible <details> output blocks and inlined figures.

Wired in as an opt-in CMake feature (off by default, depends on
WITH_TUTORIALS) with its own install component (Halide_Tutorial) and
directory knob (Halide_INSTALL_TUTORIALDIR). Requires no changes to the
lesson sources themselves, aside from fixing lesson 21's two source files
to have distinct titles like the other multi-part lessons (10, 16) already
do, and adding gdb/lldb-friendly compile flags gated behind the new feature.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Builds the Doxygen API docs (WITH_DOCS) and the new tutorials website
(WITH_TUTORIAL_WEBSITE) on release and on manual dispatch, then wholesale-
replaces docs/ and tutorials/ in halide/halide.github.com via the same
GitHub App used by the existing LLVM-updater workflows.

Manual runs default to a dry run (build + diff only, uploads the site as a
workflow artifact) rather than pushing, and can target a personal fork via
the target_repo input to rehearse a real push safely.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Adds Halide_INSTALL_DOXYGENDIR (mirroring Halide_INSTALL_TUTORIALDIR) and a
dedicated Halide_Doxygen install component, so the generated API docs are no
longer bundled under Halide_Documentation alongside README/LICENSE/the raw
tutorial sources.

This lets deploy-docs.yml drive the copy into halide.github.com entirely
through cmake --install: configuring with
-DHalide_INSTALL_DOXYGENDIR=docs -DHalide_INSTALL_TUTORIALDIR=tutorials and
installing straight into the checkout gives an exact docs/ and tutorials/
layout match, with no staging directory or path-guessing needed.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@alexreinking
alexreinking requested a review from abadams August 16, 2026 07:04
@codecov

codecov Bot commented Aug 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.04%. Comparing base (8cf05ac) to head (743b5cc).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #9347      +/-   ##
==========================================
- Coverage   70.06%   70.04%   -0.03%     
==========================================
  Files         258      259       +1     
  Lines       78702    79180     +478     
  Branches    19160    19317     +157     
==========================================
+ Hits        55143    55461     +318     
- Misses      17871    17914      +43     
- Partials     5688     5805     +117     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant