Implement composable, rerunnable story sections.

Adds infrastructure for organizing tutorial generation into reusable sections
that can be selectively regenerated or composed together.

Core features:
- Section context manager via driver.section(title, anchor)
- CLI flags: --only-sections, --skip-sections, --merge-into, --section-mode
- Automatic heading level management (H2 for top-level, H3+ for nested)
- Section filtering with skip taking precedence over only
- Markdown merging in replace/append/standalone modes

Section execution control:
- SectionProxy evaluates to False when filtered out
- Allows conditional execution: `with section(...) as s: if s: ...`
- Prevents expensive browser automation when sections are skipped

Implementation:
- Added TypedDict types for strong typing (SectionMetadata, etc.)
- Section tracking via section_elements dict and section_stack list
- Markdown extraction/merging preserves section order
- Updated generate_rule_builder_tutorial.py with 10 example sections

Tests: 19/19 passing
- Section tracking and filtering
- Heading level auto-increment
- SectionProxy truthiness and execution skipping
- Markdown extraction and merging (replace/append/standalone)
- Section order preservation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: jmchilton

lib/galaxy/selenium/cli.py

@@ -20,6 +20,8 @@
 from .navigates_galaxy import galaxy_timeout_handler
 from .stories import (
     NoopStory,
+    SectionMode,
+    SectionProxy,
     Story,
     StoryProtocol,
 )
@@ -97,6 +99,35 @@ def add_story_arguments(parser):
         default=None,
         help="Description for the generated story",
     )
+    parser.add_argument(
+        "--only-sections",
+        type=str,
+        default=None,
+        help='Comma-separated list of section anchors to generate (e.g., "basics,advanced")',
+    )
+    parser.add_argument(
+        "--skip-sections",
+        type=str,
+        default=None,
+        help="Comma-separated list of section anchors to skip",
+    )
+    parser.add_argument(
+        "--list-sections",
+        action="store_true",
+        help="List all available sections and exit (requires running the script)",
+    )
+    parser.add_argument(
+        "--merge-into",
+        type=str,
+        default=None,
+        help="Path to existing markdown file to merge sections into",
+    )
+    parser.add_argument(
+        "--section-mode",
+        choices=['replace', 'append', 'standalone'],
+        default='standalone',
+        help="How to handle sections: replace existing, append to existing, or standalone (default)",
+    )
 
     return parser
 
@@ -137,7 +168,28 @@ def __init__(self, args):
 
             title = args.story_title or "Galaxy Tutorial"
             description = args.story_description or ""
-            self.story: StoryProtocol = Story(title, description, args.story_output)
+
+            # Parse section filters
+            only_sections = None
+            skip_sections = None
+            if hasattr(args, "only_sections") and args.only_sections:
+                only_sections = set(s.strip() for s in args.only_sections.split(','))
+            if hasattr(args, "skip_sections") and args.skip_sections:
+                skip_sections = set(s.strip() for s in args.skip_sections.split(','))
+
+            # Get section mode
+            section_mode: SectionMode = getattr(args, "section_mode", "standalone")
+            merge_target = getattr(args, "merge_into", None)
+
+            self.story: StoryProtocol = Story(
+                title,
+                description,
+                args.story_output,
+                only_sections=only_sections,
+                skip_sections=skip_sections,
+                merge_target=merge_target,
+                section_mode=section_mode,
+            )
         else:
             self.story = NoopStory()
 
@@ -167,6 +219,18 @@ def screenshot(self, label: str, caption: Optional[str] = None) -> None:
             # Add to story
             self.story.add_screenshot(target, caption or label)
 
+    def section(self, title: str, anchor: str) -> SectionProxy:
+        """Create a story section context manager.
+
+        Args:
+            title: Display title for the section
+            anchor: Unique identifier for the section (used for filtering/merging)
+
+        Returns:
+            SectionProxy context manager
+        """
+        return SectionProxy(self, title, anchor)
+
     @property
     def default_timeout(self):
         return 15

lib/galaxy/selenium/context.py

@@ -10,6 +10,7 @@
     galaxy_timeout_handler,
     NavigatesGalaxy,
 )
+from .stories import SectionProxy
 
 
 class GalaxySeleniumContext(NavigatesGalaxy):
@@ -116,6 +117,18 @@ def document_file(self, file_path: str, caption: Optional[str] = None):
 
         self.document("\n".join(markdown_parts))
 
+    def section(self, title: str, anchor: str) -> SectionProxy:
+        """Create a story section context manager.
+
+        Args:
+            title: Display title for the section
+            anchor: Unique identifier for the section (used for filtering/merging)
+
+        Returns:
+            SectionProxy context manager
+        """
+        return SectionProxy(self, title, anchor)
+
     @abstractmethod
     def _screenshot_path(self, label: str, extension=".png") -> Optional[str]:
         """Path to store screenshots in."""

lib/galaxy/selenium/scripts/generate_rule_builder_tutorial.py

@@ -2,12 +2,33 @@
 """Script to generate a tutorial for the Galaxy Rule Builder.
 
 This script demonstrates using the Story class to create user documentation
-outside of the test framework.
+outside of the test framework with composable, rerunnable sections.
 
 Usage:
+    # Generate full tutorial
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial
+
+    # Generate only specific sections
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial \
+        --only-sections "workbook_example_1,rules_example_1"
+
+    # Skip sections
     python generate_rule_builder_tutorial.py \
         --galaxy_url http://localhost:8081 \
         --story-output ./rules_tutorial \
+        --skip-sections "workbook_example_3,workbook_example_4"
+
+    # Regenerate one section and merge into existing
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial_v2 \
+        --only-sections "workbook_example_1" \
+        --merge-into ./rules_tutorial/story.md \
+        --section-mode replace
 """
 import argparse
 import sys
@@ -52,31 +73,59 @@ def generate_rule_builder_tutorial(has_driver, include_result=False):
     has_driver.home()
     has_driver.ensure_rules_activity_enabled()
 
-    with example_history(has_driver, "Workbook Example 1"):
-        has_driver.upload_example_1_full_wizard()
-        has_driver.home()
-        has_driver.upload_workbook_example_1(include_result=include_result)
-    with example_history(has_driver, "Workbook Example 2"):
-        has_driver.upload_workbook_example_2_prereq_pick_a_collection()
-        has_driver.home()
-        has_driver.upload_workbook_example_2(include_result=include_result)
-    with example_history(has_driver, "Workbook Example 3"):
-        has_driver.upload_workbook_example_3(include_result=include_result)
-    with example_history(has_driver, "Workbook Example 4"):
-        has_driver.upload_workbook_example_4(include_result=include_result)
-
-    with example_history(has_driver, "Rules Example 1"):
-        has_driver.upload_rules_example_1(include_result=include_result)
-    with example_history(has_driver, "Rules Example 2"):
-        has_driver.upload_rules_example_2(include_result=include_result)
-    with example_history(has_driver, "Rules Example 3"):
-        has_driver.upload_rules_example_3(include_result=include_result)
-    with example_history(has_driver, "Rules Example 4"):
-        has_driver.upload_rules_example_4(include_result=include_result)
-    with example_history(has_driver, "Rules Example 5"):
-        has_driver.upload_rules_example_5(include_result=include_result)
-    with example_history(has_driver, "Rules Example 6"):
-        has_driver.upload_rules_example_6(include_result=include_result)
+    with has_driver.section("Workbook Example 1", "workbook_example_1") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 1"):
+                has_driver.upload_example_1_full_wizard()
+                has_driver.home()
+                has_driver.upload_workbook_example_1(include_result=include_result)
+
+    with has_driver.section("Workbook Example 2", "workbook_example_2") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 2"):
+                has_driver.upload_workbook_example_2_prereq_pick_a_collection()
+                has_driver.home()
+                has_driver.upload_workbook_example_2(include_result=include_result)
+
+    with has_driver.section("Workbook Example 3", "workbook_example_3") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 3"):
+                has_driver.upload_workbook_example_3(include_result=include_result)
+
+    with has_driver.section("Workbook Example 4", "workbook_example_4") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 4"):
+                has_driver.upload_workbook_example_4(include_result=include_result)
+
+    with has_driver.section("Rules Example 1", "rules_example_1") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 1"):
+                has_driver.upload_rules_example_1(include_result=include_result)
+
+    with has_driver.section("Rules Example 2", "rules_example_2") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 2"):
+                has_driver.upload_rules_example_2(include_result=include_result)
+
+    with has_driver.section("Rules Example 3", "rules_example_3") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 3"):
+                has_driver.upload_rules_example_3(include_result=include_result)
+
+    with has_driver.section("Rules Example 4", "rules_example_4") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 4"):
+                has_driver.upload_rules_example_4(include_result=include_result)
+
+    with has_driver.section("Rules Example 5", "rules_example_5") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 5"):
+                has_driver.upload_rules_example_5(include_result=include_result)
+
+    with has_driver.section("Rules Example 6", "rules_example_6") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 6"):
+                has_driver.upload_rules_example_6(include_result=include_result)
 
 
 @contextmanager

lib/galaxy/selenium/stories/__init__.py

@@ -6,13 +6,27 @@
 """
 
 from .story import (
+    ElementMetadata,
+    ElementType,
     NoopStory,
+    SectionMetadata,
+    SectionMetadataInput,
+    SectionMode,
+    SectionProxy,
     Story,
+    StoryElement,
     StoryProtocol,
 )
 
 __all__ = [
     "Story",
     "NoopStory",
     "StoryProtocol",
+    "SectionProxy",
+    "SectionMetadata",
+    "SectionMetadataInput",
+    "SectionMode",
+    "ElementMetadata",
+    "ElementType",
+    "StoryElement",
 ]