Cover Python syntax surface and add example graph

Author: adewale

CHANGELOG.md

@@ -23,11 +23,14 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0
 - Example source verifier, formatter, embedded-source build step, and golden parity check.
 - GitHub Actions verification workflow.
 - `iterators` and `generator-expressions` examples to make the Iteration arc explicit.
+- Syntax coverage examples for loop control, loop `else`, assertions, deletion, scope rebinding, positional-only parameters, assignment expressions, `yield from`, exception chaining/groups, advanced match patterns, inheritance, metaclasses, async iteration/context managers, import aliases, and specialized operators/literals.
+- Optional `see_also` example graph links with validation tests.
 
 ### Changed
 
 - Example walkthroughs now pair prose, source fragments, and output evidence.
 - Iteration examples now frame Python iteration as a value-stream protocol: producers, consumers, eager containers, lazy streams, and one-pass iterators.
+- The quality rubric now requires explicit syntax-surface coverage and graph-style conceptual links for neighboring examples.
 - Read-only code highlighting is handled by Shiki; editable code highlighting is handled by CodeMirror.
 - Prototype routes under `/layout-options/*` bypass the Worker Cache API and return `Cache-Control: no-store`.
 - Static assets use immutable cache headers only on fingerprinted filenames.

README.md

@@ -6,7 +6,7 @@ Production: <https://www.pythonbyexample.dev> (`workers.dev` remains enabled as
 
 ## Features
 
-- 52 curated Python 3.13 examples in learning order
+- 69 curated Python 3.13 examples in learning order
 - Literate source/output cells for each example walkthrough
 - Editable complete examples powered by CodeMirror
 - Read-only syntax highlighting powered by Shiki

docs/example-graph-see-also.md

@@ -0,0 +1,48 @@
+# See also links and the example graph
+
+The catalog should stay readable as a linear tour, but Python concepts are not purely linear. `See also` links turn the examples into a small concept graph without adding visual noise to every paragraph.
+
+## Why add them
+
+- **Boundaries become explicit.** A page can point to the neighboring feature learners often confuse it with: `break` vs loop `else`, comprehensions vs generator expressions, `assert` vs exceptions, property vs method.
+- **Prerequisites and follow-ups are visible.** A syntax page can stay compact while sending readers to the examples that explain the underlying model.
+- **Coverage becomes auditable.** If every edge points to a real slug, tests can catch broken conceptual links and make missing syntax harder to overlook.
+- **The site becomes a graph, not just a list.** Previous/next remains the recommended path; See also links expose cross-cutting concepts.
+
+## Risks
+
+- **Too many links can dilute the page.** Use two to four links, not a tag cloud.
+- **Circular links can feel arbitrary.** Cycles are fine when concepts truly reinforce each other, but every edge should answer “why should I read this next?”
+- **Maintenance cost increases.** Renaming or deleting a slug must update graph edges. Automated tests should validate every `see_also` slug.
+- **SEO and crawl shape changes.** Internal links help discovery, but repeated boilerplate links should not crowd the main lesson.
+
+## Design rule
+
+`See also` should be reserved for conceptual edges:
+
+- prerequisite: `yield-from` → `generators`
+- contrast: `assignment-expressions` → `conditionals`
+- continuation: `async-iteration-and-context` → `async-await`
+- shared mechanism: `delete-statements` → `mutability`
+
+Do not use it as a category list. The home page and previous/next navigation already provide the linear table of contents.
+
+## Current implementation
+
+Example Markdown frontmatter may include:
+
+```toml
+see_also = [
+  "for-loops",
+  "while-loops",
+]
+```
+
+The loader exposes `see_also`, the example renderer displays a compact `See also` section, and tests verify that every linked slug exists and does not point to itself.
+
+## Future improvements
+
+- Add a graph audit script that reports orphan pages, high-degree pages, and missing reciprocal links.
+- Show short edge labels later, e.g. `contrast`, `prerequisite`, `next depth`.
+- Use graph data to recommend examples on 404 pages or search results.
+- Keep the first version minimal until we know the links improve reading rather than distracting from the code.

docs/example-quality-rubric.md

@@ -11,7 +11,7 @@ Score each example on a 10 point scale:
 5. **Source/result pairing (0-1.25)** — each important source fragment has nearby output that proves the semantic point, not merely that the code ran.
 6. **Concept decomposition (0-1.0)** — the example breaks the concept into meaningful parts instead of presenting one compressed trick.
 7. **Progressive walkthrough (0-0.75)** — each cell introduces one new idea, and the sequence builds toward the complete concept. Single-cell examples are acceptable only for intentionally atomic concepts.
-8. **Representative coverage (0-0.75)** — the code covers the forms promised by the title, summary, and prose. Do not claim lists, dictionaries, and sets while showing only two of them.
+8. **Representative coverage (0-0.75)** — the code covers the forms promised by the title, summary, and prose, and the catalog has an explicit home for every common Python syntax form. Do not claim lists, dictionaries, and sets while showing only two of them; do not let syntax such as `break`, `continue`, `assert`, `nonlocal`, `yield from`, or `async for` exist only as untested assumptions.
 9. **Contrast and boundary clarity (0-0.75)** — when a feature is commonly confused with another feature, the example shows the distinction: comprehension vs loop, `sorted()` vs `list.sort()`, `lambda` vs `def`, `==` vs `is`, generator vs list, property vs method, and similar boundaries.
 10. **Practical usefulness (0-1.0)** — names, data, and outputs resemble simplified real code rather than toy placeholders; the example gives the feature a reason to exist.
 
@@ -22,6 +22,7 @@ Release gates outside the score:
 - page layout remains restrained and readable
 - examples verify under the configured Python version
 - generated embedded source and asset manifests are up to date
+- syntax-surface tests prove that each major statement, expression marker, loop-control form, function-signature marker, pattern form, import form, and async form has a runnable example
 - iteration examples identify what produces values, what consumes values, whether values are stored or streamed, and whether the stream is reusable or one-pass
 
 Quality bands:
@@ -39,6 +40,7 @@ Flag these during review even when the code is correct:
 
 - A multi-part concept has only one cell.
 - The title or prose promises forms not shown by code.
+- A Python syntax form appears in the language-tour checklist but has no runnable example.
 - Output is a single scalar for a collection transformation, so the reader cannot see the shape of the result.
 - A concept with a common confusion has no contrast or boundary example.
 - More than half of nonblank code lines are `print(...)` calls.
@@ -63,3 +65,4 @@ Before publishing or substantially editing an example, ask:
 7. For iteration examples, what produces values, what consumes them, and are they stored eagerly or streamed lazily?
 8. What neighboring feature would a learner confuse this with, and does the page explain the boundary?
 9. Does the data shape explain why this feature exists?
+10. What syntax form would disappear from the catalog if this page were removed, and is that covered somewhere else?

public/site.css

@@ -9,7 +9,7 @@
 
 ROOT = Path(__file__).resolve().parents[1]
 SOURCE_DIR = ROOT / "src" / "example_sources"
-FRONTMATTER_ORDER = ["slug", "title", "section", "summary", "doc_path", "min_python", "version_sensitive", "version_notes"]
+FRONTMATTER_ORDER = ["slug", "title", "section", "summary", "doc_path", "see_also", "min_python", "version_sensitive", "version_notes"]
 
 
 def toml_value(value: Any) -> str:

public/site.06e133dcde6a.css public/site.dc51488c4ed9.csspublic/site.06e133dcde6a.css renamed to public/site.dc51488c4ed9.css

@@ -303,6 +303,13 @@ def render_example_page(example, output=None, code=None, execution_time_ms=None)
         for index, step in enumerate(walkthrough, 1)
     )
     notes_html = "".join(f"<li>{note}</li>" for note in notes)
+    see_also_examples = [get_example(slug) for slug in example.get("see_also", [])]
+    see_also_links = "".join(
+        f'<li><a class="text-link" href="/examples/{html.escape(item["slug"])}">{html.escape(item["title"])}</a></li>'
+        for item in see_also_examples
+        if item is not None
+    )
+    see_also_html = f'<section class="see-also"><h2>See also</h2><ul>{see_also_links}</ul></section>' if see_also_links else ""
     content = _replace(
         _template("example.html"),
         {
@@ -312,6 +319,7 @@ def render_example_page(example, output=None, code=None, execution_time_ms=None)
             "SUMMARY": html.escape(example["summary"]),
             "WALKTHROUGH": walkthrough_html,
             "NOTES": notes_html,
+            "SEE_ALSO": see_also_html,
             "PREVIOUS_LINK": previous_link,
             "NEXT_LINK": next_link,
             "SLUG": html.escape(example["slug"]),

scripts/format_examples.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
-ASSET_PATHS = {'SITE_CSS': '/site.06e133dcde6a.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = 'd3f04ba18268'
+ASSET_PATHS = {'SITE_CSS': '/site.dc51488c4ed9.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
+HTML_CACHE_VERSION = '5cd6e8013a84'

src/app.py

@@ -151,6 +151,7 @@ def example_to_dict(filename: str, catalog: ExampleCatalog) -> dict[str, Any]:
         "doc_url": f"{catalog.docs_base_url}{doc_path}",
         "explanation": intro,
         "notes": notes,
+        "see_also": list(frontmatter.get("see_also", [])),
         "walkthrough": [{"prose": prose, "code": cell.source} for cell in cells for prose in cell.prose],
         "cells": [{"prose": cell.prose, "code": cell.source, "output": cell.output, "line": cell.line} for cell in cells],
         "code": code,