Add subsection support across exporters

CHANGELOG.md

@@ -10,6 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 (unreleased)=
 ## [Unreleased](https://github.com/jeertmans/manim-slides/compare/v5.5.2...HEAD)
 
+(unreleased-added)=
+### Added
+
+- Introduced `Slide.next_subsection()` to record intra-slide checkpoints. New
+  presenter/convert flags (`--subsections`, `--html-subsections`,
+  `--pdf-subsections`, and `--pptx-subsections`) allow the Qt/HTML presenters,
+  PDF exporter, and PowerPoint converter to pause at those subsections or split
+  slides when explicitly requested.
+
 (unreleased-changed)=
 ### Changed
 

README.md

@@ -61,7 +61,11 @@ The documentation is available [online](https://eertmans.be/manim-slides/).
 
 Call `self.next_slide()` every time you want to create a pause between
 animations, and `self.next_slide(loop=True)` if you want the next slide to loop
-over animations until the user presses continue:
+over animations until the user presses continue.
+Use `self.next_subsection()` when you need multiple presenter-controlled pause
+points inside a single slide (for example, Beamer overlays). Subsections keep
+the slide active, but allow the Qt/HTML presenters, PDF exports, and PowerPoint
+conversion (when requested) to pause at those intermediate states:
 
 ```python
 from manim import *  # or: from manimlib import *

docs/source/reference/api.md

@@ -15,6 +15,7 @@ use, not the methods used internally when rendering.
         canvas,
         canvas_mobjects,
         mobjects_without_canvas,
+        next_subsection,
         next_section,
         next_slide,
         remove_from_canvas,

docs/source/reference/sharing.md

@@ -186,6 +186,10 @@ frame of each slide. This allows for smooth transitions.
 In the future, we hope to provide more features to this format,
 so feel free to suggest new features too!
 
+If you authored subsections, pass `--pptx-subsections=split` to duplicate the
+slide once per subsection so clickers pause exactly where they do in the Qt/HTML
+presenters.
+
 ### Static PDF presentation
 
 If you ever need backup slides, that are only made of PDF pages
@@ -199,3 +203,7 @@ Note that you will lose all the benefits from animated slides. Therefore,
 this is only recommended to be used as a backup plan. By default, the last frame
 of each slide will be printed. This can be changed to be the first one with
 `-cframe_index=first`.
+When slides contain subsections (`self.next_subsection()`), you can opt in to
+extra PDF pages per subsection with `--pdf-subsections=all`, or keep a single
+page per slide but capture the last subsection state using
+`--pdf-subsections=final`.

manim_slides/config.py

@@ -1,5 +1,6 @@
 import json
 import shutil
+from collections.abc import Sequence
 from functools import wraps
 from inspect import Parameter, signature
 from pathlib import Path
@@ -11,6 +12,7 @@
     BaseModel,
     Field,
     FilePath,
+    NonNegativeInt,
     PositiveInt,
     PrivateAttr,
     conset,
@@ -151,6 +153,35 @@ def merge_with(self, other: "Config") -> "Config":
         return self
 
 
+class SubsectionMarker(BaseModel):  # type: ignore[misc]
+    """User-authored subsection boundary recorded before rendering."""
+
+    animation_index: NonNegativeInt
+    name: str = ""
+    auto_next: bool = False
+
+
+class SubsectionConfig(BaseModel):  # type: ignore[misc]
+    """Fully resolved subsection configuration stored after rendering."""
+
+    name: str = ""
+    auto_next: bool = False
+    start_animation: NonNegativeInt
+    end_animation: NonNegativeInt
+    start_time: float = Field(0.0, ge=0.0)
+    end_time: float = Field(0.0, ge=0.0)
+
+    @model_validator(mode="after")
+    def animations_are_monotone(self) -> "SubsectionConfig":
+        if self.end_animation < self.start_animation:
+            raise ValueError(
+                "end_animation must be greater or equal to start_animation"
+            )
+        if self.end_time < self.start_time:
+            raise ValueError("end_time must be greater or equal to start_time")
+        return self
+
+
 class BaseSlideConfig(BaseModel):  # type: ignore
     """Base class for slide config."""
 
@@ -220,17 +251,21 @@ class PreSlideConfig(BaseSlideConfig):
 
     start_animation: int
     end_animation: int
+    subsection_markers: tuple[SubsectionMarker, ...] = Field(default_factory=tuple)
 
     @classmethod
     def from_base_slide_config_and_animation_indices(
         cls,
         base_slide_config: BaseSlideConfig,
         start_animation: int,
         end_animation: int,
+        *,
+        subsection_markers: Sequence[SubsectionMarker] = (),
     ) -> "PreSlideConfig":
         return cls(
             start_animation=start_animation,
             end_animation=end_animation,
+            subsection_markers=tuple(subsection_markers),
             **base_slide_config.model_dump(),
         )
 
@@ -280,12 +315,23 @@ class SlideConfig(BaseSlideConfig):
 
     file: FilePath
     rev_file: FilePath
+    subsections: tuple[SubsectionConfig, ...] = Field(default_factory=tuple)
 
     @classmethod
     def from_pre_slide_config_and_files(
-        cls, pre_slide_config: PreSlideConfig, file: Path, rev_file: Path
+        cls,
+        pre_slide_config: PreSlideConfig,
+        file: Path,
+        rev_file: Path,
+        *,
+        subsections: Sequence[SubsectionConfig] = (),
     ) -> "SlideConfig":
-        return cls(file=file, rev_file=rev_file, **pre_slide_config.model_dump())
+        return cls(
+            file=file,
+            rev_file=rev_file,
+            subsections=tuple(subsections),
+            **pre_slide_config.model_dump(exclude={"subsection_markers"}),
+        )
 
 
 class PresentationConfig(BaseModel):  # type: ignore[misc]