Skip to content

docs(codelab): match the published Google Codelab format (issue #96)#274

Merged
haiyuan-eng-google merged 2 commits into
GoogleCloudPlatform:mainfrom
caohy1988:codelab/match-issue-96-format
Jun 2, 2026
Merged

docs(codelab): match the published Google Codelab format (issue #96)#274
haiyuan-eng-google merged 2 commits into
GoogleCloudPlatform:mainfrom
caohy1988:codelab/match-issue-96-format

Conversation

@caohy1988
Copy link
Copy Markdown
Collaborator

@caohy1988 caohy1988 commented Jun 2, 2026

Summary

Reformats the periodic-materialization codelab (docs/codelabs/periodic_materialization.md) to follow the published Google Codelab format demonstrated in the reference example codelab (Context Caching in BigQuery, issue #96). Runnable commands and queries are preserved; the changes are presentation/reader-flow oriented.

The dual-purpose <!-- colab:* --> markers are HTML comments invisible to claat, so the rendered codelab now matches #96 and the self-contained Colab notebook still generates from the same source.

This PR also adds the BigQuery Studio graph visualization (images/graph-visualization.png) to the Query the decision trace step, using the same generated-notebook image embedding path as the existing codelab images.

Format changes (to match #96)

  • Frontmatter -> ----delimited YAML: id, summary, authors, keywords: category:..., product:..., layout: paginated (drops categories/tags/status/feedback link in favor of the BigQuery Agent Analytics Roadmap #96 metadata set).
  • Durations -> MM:SS per section (claat totals 42 min, and the intro estimate now matches).
  • Tips/notes -> claat asides (> aside positive / > aside negative). Renders as 6 special + 1 warning callout boxes.
  • Section titles sentence-cased and de-numbered (dropped Phase N:), matching BigQuery Agent Analytics Roadmap #96's descriptive step titles; all in-body cross-references updated to track the new titles.
  • Bold action phrases ("Run the following command"), console output fences, and an intro workflow diagram (images/context-graph-flow.png).
  • Query step visual evidence -> BigQuery Studio Graph tab screenshot (images/graph-visualization.png) with qualified GRAPH ${DATASET}.agent_decisions_graph guidance.
  • Ending reshaped to ## Congratulations + #### What you've learned + #### Reference docs.

Generator change

claat aside marker lines (> aside positive / > aside negative) would otherwise leak into the Colab notebook as literal blockquote text. Taught scripts/generate_colab_from_codelab.py to strip those marker lines (same pattern it already uses for Duration: lines) so the callout body renders as a plain Markdown blockquote in Colab. Added tests/test_generate_colab_asides.py.

Verification

  • generate_colab_from_codelab.py --check passes (notebook regenerated, no drift).
  • Notebook: 0 leaked aside/Duration lines, 0 broken relative image refs, 0 curl (still self-contained), 3 base64-embedded PNG images.
  • Graph visualization prose avoids a stale fixed node/edge-count contract and uses the dataset-qualified graph query form.
  • claat export builds clean (exit 0); images copied into img/; asides render as callout boxes.
  • pytest tests/test_generate_colab_asides.py tests/test_generate_colab_images.py tests/test_codelab_embedded_artifacts.py -> 12 passed.

caohy1988 added 2 commits June 2, 2026 13:52
…shed Google Codelab format

Aligns docs/codelabs/periodic_materialization.md with the reference codelab
format in issue GoogleCloudPlatform#96 (Context Caching in BigQuery), while preserving the
dual-purpose colab markers so the self-contained Colab notebook still
generates.

Format changes:
- Frontmatter: ---delimited YAML with id, summary, authors, keywords
  (category:/product:), layout: paginated (drops categories/tags/status/
  feedback-link in favor of the GoogleCloudPlatform#96 metadata set).
- Per-section Duration switched to MM:SS (e.g. 05:00); total 42 min.
- Tips/notes converted to claat asides (> aside positive / > aside negative)
  -- renders as 6 special + 1 warning callout boxes.
- Section titles sentence-cased and de-numbered (dropped 'Phase N:'),
  matching GoogleCloudPlatform#96's descriptive step titles; in-body cross-references updated.
- Bold action phrases, console output fences, and an intro workflow diagram.
- Ending reshaped to ## Congratulations + #### What you've learned +
  #### Reference docs.

Generator: strip claat aside marker lines (> aside positive/negative) when
building the notebook so the marker text does not leak into Colab; the
callout body renders as a plain blockquote. Adds tests/test_generate_colab_asides.py.

Notebook regenerated; --check passes. claat export builds clean (exit 0).
@haiyuan-eng-google haiyuan-eng-google merged commit d7fa797 into GoogleCloudPlatform:main Jun 2, 2026
13 checks passed
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.

2 participants