feat(lib): use and add more config option (#452)

* feat(lib): use and add more config option

Closes #441

* feat(lib): add support for more options and test them

* chore(docs): add attributes to documentation

* chore(docs): sort members by member type

* chore(docs): small improvements

* chore(docs): cleanup

CHANGELOG.md

@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `manim-slides checkhealth` command to easily obtain important information
   for debug purposes.
   [#458](https://github.com/jeertmans/manim-slides/pull/458)
+- Added support for `disable_caching` and `flush_cache` options from Manim, and
+  also the possibility to configure them through class options.
+  [#452](https://github.com/jeertmans/manim-slides/pull/452)
 
 (unreleased-chore)=
 ### Chore

manim_slides/docs/manim_slides_directive.py

@@ -283,8 +283,7 @@ def run(self):  # noqa: C901
         # Rendering is skipped if the tag skip-manim is present,
         # or if we are making the pot-files
         should_skip = (
-            "skip-manim-slides"
-            in self.state.document.settings.env.app.builder.tags.tags
+            self.state.document.settings.env.app.builder.tags.has("skip-manim-slides")
             or self.state.document.settings.env.app.builder.name == "gettext"
             or "SKIP_MANIM_SLIDES" in os.environ
         )

manim_slides/slide/base.py

@@ -3,6 +3,7 @@
 __all__ = ["BaseSlide"]
 
 import platform
+import shutil
 from abc import abstractmethod
 from collections.abc import MutableMapping, Sequence, ValuesView
 from pathlib import Path
@@ -32,6 +33,10 @@
 
 
 class BaseSlide:
+    disable_caching: bool = False
+    flush_cache: bool = False
+    skip_reversing: bool = False
+
     def __init__(
         self, *args: Any, output_folder: Path = FOLDER_PATH, **kwargs: Any
     ) -> None:
@@ -170,11 +175,23 @@ def add_to_canvas(self, **objects: Mobject) -> None:
             animations. You must still call :code:`self.add` or
             play some animation that introduces each Mobject for
             it to appear. The same applies when removing objects.
+
+        .. seealso::
+
+            :attr:`canvas` for usage examples.
         """
         self._canvas.update(objects)
 
     def remove_from_canvas(self, *names: str) -> None:
-        """Remove objects from the canvas."""
+        """
+        Remove objects from the canvas.
+
+        :param names: The names of objects to remove.
+
+        .. seealso::
+
+            :attr:`canvas` for usage examples.
+        """
         for name in names:
             self._canvas.pop(name)
 
@@ -186,8 +203,12 @@ def canvas_mobjects(self) -> ValuesView[Mobject]:
     @property
     def mobjects_without_canvas(self) -> Sequence[Mobject]:
         """
-        Return the list of objects contained in the scene, minus those present in
+        Return the list of Mobjects contained in the scene, minus those present in
         the canvas.
+
+        .. seealso::
+
+            :attr:`canvas` for usage examples.
         """
         return [
             mobject
@@ -275,7 +296,7 @@ def next_slide(
         next slide is played. By default, this is the right arrow key.
 
         :param args:
-            Positional arguments to be passed to
+            Positional arguments passed to
             :meth:`Scene.next_section<manim.scene.scene.Scene.next_section>`,
             or ignored if `manimlib` API is used.
         :param loop:
@@ -284,27 +305,38 @@ def next_slide(
             If set, next slide will play immediately play the next slide
             upon terminating.
 
-            Note that this is only supported by ``manim-slides present``
-            and ``manim-slides convert --to=html``.
+            .. warning::
+
+                Only supported by ``manim-slides present``
+                and ``manim-slides convert --to=html``.
         :param playback_rate:
             Playback rate at which the video is played.
 
-            Note that this is only supported by ``manim-slides present``.
+            .. warning::
+
+                Only supported by ``manim-slides present``.
         :param reversed_playback_rate:
             Playback rate at which the reversed video is played.
 
-            Note that this is only supported by ``manim-slides present``.
+            .. warning::
+
+                Only supported by ``manim-slides present``.
         :param notes:
             Presenter notes, in Markdown format.
 
-            Note that PowerPoint does not support Markdown.
+            .. note::
+                PowerPoint does not support Markdown formatting,
+                so the text will be displayed as is.
+
+            .. warning::
 
-            Note that this is only supported by ``manim-slides present``
-            and ``manim-slides convert --to=html/pptx``.
+                Only supported by ``manim-slides present``,
+                ``manim-slides convert --to=html`` and
+                ``manim-slides convert --to=pptx``.
         :param dedent_notes:
             If set, apply :func:`textwrap.dedent` to notes.
         :param kwargs:
-            Keyword arguments to be passed to
+            Keyword arguments passed to
             :meth:`Scene.next_section<manim.scene.scene.Scene.next_section>`,
             or ignored if `manimlib` API is used.
 
@@ -445,11 +477,17 @@ def _add_last_slide(self) -> None:
             )
         )
 
-    def _save_slides(self, use_cache: bool = True) -> None:
+    def _save_slides(
+        self,
+        use_cache: bool = True,
+        flush_cache: bool = False,
+        skip_reversing: bool = False,
+    ) -> None:
         """
         Save slides, optionally using cached files.
 
-        Note that cached files only work with Manim.
+        .. warning:
+            Caching files only work with Manim.
         """
         self._add_last_slide()
 
@@ -458,6 +496,9 @@ def _save_slides(self, use_cache: bool = True) -> None:
         scene_name = str(self)
         scene_files_folder = files_folder / scene_name
 
+        if flush_cache and scene_files_folder.exists():
+            shutil.rmtree(scene_files_folder)
+
         scene_files_folder.mkdir(parents=True, exist_ok=True)
 
         files: list[Path] = self._partial_movie_files
@@ -492,7 +533,10 @@ def _save_slides(self, use_cache: bool = True) -> None:
 
             # We only reverse video if it was not present
             if not use_cache or not rev_file.exists():
-                reverse_video_file(dst_file, rev_file)
+                if skip_reversing:
+                    rev_file = dst_file
+                else:
+                    reverse_video_file(dst_file, rev_file)
 
             slides.append(
                 SlideConfig.from_pre_slide_config_and_files(

manim_slides/slide/manim.py

@@ -13,6 +13,22 @@ class Slide(BaseSlide, Scene):  # type: ignore[misc]
     """
     Inherits from :class:`Scene<manim.scene.scene.Scene>` and provide necessary tools
     for slides rendering.
+
+    :param args: Positional arguments passed to scene object.
+    :param output_folder: Where the slide animation files should be written.
+    :param kwargs: Keyword arguments passed to scene object.
+    :cvar bool disable_caching: :data:`False`: Whether to disable the use of
+        cached animation files.
+    :cvar bool flush_cache: :data:`False`: Whether to flush the cache.
+
+        Unlike with Manim, flushing is performed before rendering.
+    :cvar bool skip_reversing: :data:`False`: Whether to generate reversed animations.
+
+        If set to :data:`False`, and no cached reversed animation
+        exists (or caching is disabled) for a given slide,
+        then the reversed animation will be simply the same
+        as the original one, i.e., ``rev_file = file``,
+        for the current slide config.
     """
 
     @property
@@ -102,16 +118,29 @@ def next_slide(
         )
 
     def render(self, *args: Any, **kwargs: Any) -> None:
-        """MANIM render."""
+        """MANIM renderer."""
         # We need to disable the caching limit since we rely on intermediate files
         max_files_cached = config["max_files_cached"]
         config["max_files_cached"] = float("inf")
 
+        flush_manim_cache = config["flush_cache"]
+
+        if flush_manim_cache:
+            # We need to postpone flushing *after* we saved slides
+            config["flush_cache"] = False
+
         super().render(*args, **kwargs)
 
         config["max_files_cached"] = max_files_cached
 
-        self._save_slides()
+        self._save_slides(
+            use_cache=not (config["disable_caching"] or self.disable_caching),
+            flush_cache=(config["flush_cache"] or self.flush_cache),
+            skip_reversing=self.skip_reversing,
+        )
+
+        if flush_manim_cache:
+            self.renderer.file_writer.flush_cache_directory()
 
 
 class ThreeDSlide(Slide, ThreeDScene):  # type: ignore[misc]

manim_slides/slide/manimlib.py

@@ -62,7 +62,11 @@ def _start_at_animation_number(self) -> Optional[int]:
     def run(self, *args: Any, **kwargs: Any) -> None:
         """MANIMGL renderer."""
         super().run(*args, **kwargs)
-        self._save_slides(use_cache=False)
+        self._save_slides(
+            use_cache=False,
+            flush_cache=self.flush_cache,
+            skip_reversing=self.skip_reversing,
+        )
 
 
 class ThreeDSlide(Slide):