Add a Python-based tutorials website generator and deploy workflow - #9347
Open
alexreinking wants to merge 4 commits into
Open
Add a Python-based tutorials website generator and deploy workflow#9347alexreinking wants to merge 4 commits into
alexreinking wants to merge 4 commits into
Conversation
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>
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
tutorial/figures/generate_output_snippets.sh+halide.github.com/tutorials/gen_tutorials.sh) with a single in-tree Python tool undertutorial/website/, wired in as an opt-in CMake feature (WITH_TUTORIAL_WEBSITE, off by default, requiresWITH_TUTORIALS) with its own install component (Halide_Tutorial) and directory knob (Halide_INSTALL_TUTORIALDIR).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..cpp/.shsources 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..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 tohalide/halide.github.comusing 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.Test plan
-DWITH_TUTORIAL_WEBSITE=ON; ran the generator via LLDB and confirmed real captured output (e.g.HL_DEBUG_CODEGENtrace for lesson 3,print_loop_nest/tracing output for lessons 4/5/8/9/18/19).lesson_15_generators_usage.sh) all render correctly.cmake --install --component Halide_Tutoriallands files undershare/tutorial/.ruff check/ruff formatand this repo'scheck_cmake_style.py/check_cmake_file_lists.pyall pass; fullpre-commit run --all-files-equivalent hooks pass on every commit.deploy-docs.ymlitself hasn't been run in CI yet -- recommend triggering it once viaworkflow_dispatchwith the defaultdry_run: true(safe, no push) to sanity-check the artifact before relying on it for a real release.🤖 Generated with Claude Code