Skip to content

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

Draft
alexreinking wants to merge 1 commit into
alexreinking/python-tutorial-parityfrom
alexreinking/new-tutorial-site
Draft

Add a Python-based tutorials website generator and deploy workflow#9347
alexreinking wants to merge 1 commit into
alexreinking/python-tutorial-parityfrom
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

Fixes #8146

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
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 (e3e0ca0) to head (36b64b7).

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #9347      +/-   ##
==========================================
- Coverage   70.11%   70.04%   -0.08%     
==========================================
  Files         259      259              
  Lines       79135    79135              
  Branches    19286    19286              
==========================================
- Hits        55487    55429      -58     
- Misses      17880    17883       +3     
- Partials     5768     5823      +55     

☔ 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.

@alexreinking
alexreinking force-pushed the alexreinking/new-tutorial-site branch from 743b5cc to 36b64b7 Compare August 17, 2026 00:03
@alexreinking
alexreinking changed the base branch from main to alexreinking/tutorial-improvements August 17, 2026 04:57
@alexreinking
alexreinking force-pushed the alexreinking/new-tutorial-site branch 2 times, most recently from c32e0d3 to 61ba765 Compare August 17, 2026 05:08
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 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.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@alexreinking
alexreinking changed the base branch from alexreinking/tutorial-improvements to alexreinking/python-tutorial-parity August 17, 2026 05:14
@alexreinking
alexreinking force-pushed the alexreinking/new-tutorial-site branch from 61ba765 to c7f5d84 Compare August 17, 2026 05:14
@alexreinking
alexreinking marked this pull request as draft August 17, 2026 05:47
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.

Three tutorials missing on the website.

1 participant