diff --git a/docs/source/reference/api.md b/docs/source/reference/api.md index 62ea77fd..6cc19c79 100644 --- a/docs/source/reference/api.md +++ b/docs/source/reference/api.md @@ -6,7 +6,7 @@ Thefore, we only document here the methods we think the end-user will ever use, ```{eval-rst} .. autoclass:: manim_slides.Slide - :members: start_loop, end_loop, pause, play + :members: start_loop, end_loop, pause, next_slide .. autoclass:: manim_slides.ThreeDSlide :members: diff --git a/manim_slides/slide.py b/manim_slides/slide.py index f81dd885..f5a89304 100644 --- a/manim_slides/slide.py +++ b/manim_slides/slide.py @@ -3,6 +3,7 @@ import shutil import subprocess from typing import Any, List, Optional +from warnings import warn from tqdm import tqdm @@ -90,8 +91,51 @@ def play(self, *args: Any, **kwargs: Any) -> None: super().play(*args, **kwargs) self.current_animation += 1 - def pause(self) -> None: - """Creates a new slide with previous animations.""" + def next_slide(self): + """ + Creates a new slide with previous animations. + + This usually means that the user will need to press some key before the + next slide is played. By default, this is the right arrow key. + + + .. note:: + + Calls to :func:`next_slide` at the very beginning or at the end are + not needed, since they are automatically added. + + .. warning:: + + This is not allowed to call :func:`next_slide` inside a loop. + + Examples + -------- + + The following contains 3 slides: + + #. the first with nothing on it; + #. the second with "Hello World!" fading in; + #. and the last with the text fading out; + + .. code-block:: python + + from manim import * + from manim_slides import Slide + + class Example(Slide): + def construct(self): + text = Text("Hello World!") + + self.next_slide() + self.play(FadeIn(text)) + + self.next_slide() + self.play(FadeOut(text)) + """ + assert ( + self.loop_start_animation is None + ), "You cannot call `self.next_slide()` inside a loop" + self.slides.append( SlideConfig( type=SlideType.slide, @@ -103,6 +147,20 @@ def pause(self) -> None: self.current_slide += 1 self.pause_start_animation = self.current_animation + def pause(self) -> None: + """ + Creates a new slide with previous animations. + + .. deprecated:: 4.9.3 + Use :func:`next_slide` instead. + """ + warn( + "`self.pause()` is deprecated. Use `self.next_slide()` instead.", + DeprecationWarning, + stacklevel=2, + ) + self.next_slide() + def add_last_slide(self) -> None: """Adds a 'last' slide to the end of slides.""" @@ -123,12 +181,37 @@ def add_last_slide(self) -> None: ) def start_loop(self) -> None: - """Starts a loop.""" + """ + Starts a loop. End it with :func:`end_loop`. + + A loop will automatically replay the slide, i.e., everything between + :func:`start_loop` and :func:`end_loop`, upon reaching end. + + Examples + -------- + + The following contains one slide that will loop endlessly. + + .. code-block:: python + + from manim import * + from manim_slides import Slide + + class Example(Slide): + def construct(self): + dot = Dot(color=BLUE) + + self.start_loop() + + self.play(Indicate(dot)) + + self.end_loop() + """ assert self.loop_start_animation is None, "You cannot nest loops" self.loop_start_animation = self.current_animation def end_loop(self) -> None: - """Ends an existing loop.""" + """Ends an existing loop. See :func:`start_loop` for more details.""" assert ( self.loop_start_animation is not None ), "You have to start a loop before ending it"