chore(lib): use next_slide not pause (#151)

* chore(lib): use `next_slide` not `pause`

This deprecates `pause` function in favor to `next_slide`, that will also be called by `next_section` in the future.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

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:

manim_slides/slide.py

@@ -3,6 +3,7 @@ import platform
 import shutil
 import subprocess
 from typing import Any, List, Optional
+from warnings import warn
 
 from tqdm import tqdm
 
@@ -90,8 +91,51 @@ class Slide(Scene):  # type:ignore
         super().play(*args, **kwargs)
         self.current_animation += 1
 
-    def pause(self) -> None:
+    def next_slide(self):
-        """Creates a new slide with previous animations."""
+        """
+        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 @@ class Slide(Scene):  # type:ignore
         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 @@ class Slide(Scene):  # type:ignore
         )
 
     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"