chore(lib): moved Sphinx directive from docs to sphinxext

* chore(dev): move dev-dependencies inside dependency-groups

* fix(ci): ci was not broken

.github/workflows/tests.yml

@@ -96,7 +96,7 @@ jobs:
       uses: ssciwr/setup-mesa-dist-win@v2
 
     - name: Run pytest
-      run: uv run --python ${{ matrix.pyversion }} --frozen --extra tests pytest
+      run: uv run --python ${{ matrix.pyversion }} --frozen --group tests --no-dev pytest
 
     - name: Upload to codecov.io
       uses: codecov/codecov-action@v5

.pre-commit-config.yaml

@@ -21,18 +21,18 @@ repos:
     exclude: poetry.lock
     args: [--autofix, --trailing-commas]
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.9.1
+  rev: v0.11.5
   hooks:
   - id: ruff
     args: [--fix]
   - id: ruff-format
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.14.1
+  rev: v1.15.0
   hooks:
   - id: mypy
     additional_dependencies: [types-requests, types-setuptools]
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.3.0
+  rev: v2.4.1
   hooks:
   - id: codespell
     additional_dependencies:

.readthedocs.yaml

@@ -6,13 +6,13 @@ build:
   apt_packages:
   - libpango1.0-dev
   - ffmpeg
+  jobs:
+    post_create_environment:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --group docs --no-dev --no-cache
 sphinx:
   builder: html
   configuration: docs/source/conf.py
   fail_on_warning: true
-python:
-  install:
-  - method: pip
-    path: .
-    extra_requirements:
-    - docs

CHANGELOG.md

@@ -8,7 +8,105 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 <!-- start changelog -->
 
 (unreleased)=
-## [Unreleased](https://github.com/jeertmans/manim-slides/compare/v5.3.1...HEAD)
+## [Unreleased](https://github.com/jeertmans/manim-slides/compare/v5.5.1...HEAD)
+
+(unreleased-chore)=
+### Chore
+
+- Moved `docs` and `tests` extras, as well as `dev-dependencies`,
+  inside groups in `dependency-groups`. This could break existing code
+  when using one of those extras, but as they were not part of the public API,
+  we do not consider this to be a **breaking change**.
+  [#542](https://github.com/jeertmans/manim-slides/pull/542)
+- Moved `manim_slides.docs.manim_slides_directive` to `manim_slides.sphinxext.manim_slides_directive`.
+  This is a **breaking change** because documentation configs have
+  to be updated.
+  [#242](https://github.com/jeertmans/manim-slides/pull/242)
+
+(v5.5.1)=
+## [v5.5.1](https://github.com/jeertmans/manim-slides/compare/v5.5.0...v5.5.1)
+
+(v5.5.1-changed)=
+### Changed
+
+- HTML template now always includes the *notes* plugin so that the speaker
+  view is always available. Previously, it was only included if the slides
+  had notes.
+  [#538](https://github.com/jeertmans/manim-slides/pull/538)
+- Pressing <kbd>SPACE</kbd> key now pauses the slides, instead of skipping it.
+  Previously, it was not possible to pause HTML slides, which can be very annoying
+  when trying to explain something.
+  [#539](https://github.com/jeertmans/manim-slides/pull/539)
+
+(v5.5.0)=
+## [v5.5.0](https://github.com/jeertmans/manim-slides/compare/v5.4.2...v5.5.0)
+
+(v5.5.0-added)=
+### Added
+
+- Added `max_duration_before_split_reverse` and `num_processes` class variables.
+  [#439](https://github.com/jeertmans/manim-slides/pull/439)
+- Added `src = ...` filepath argument to allow inserting external
+  videos as slides.
+  [#526](https://github.com/jeertmans/manim-slides/pull/526)
+
+(v5.5.0-changed)=
+### Changed
+
+- Automatically split large video animations into smaller chunks
+  for lightweight (and potentially faster) reversed animations generation.
+  [#439](https://github.com/jeertmans/manim-slides/pull/439)
+
+(v5.5.0-chore)=
+### Chore
+
+- Trimmed whitespaces in HTML template.
+  [#443](https://github.com/jeertmans/manim-slides/pull/443)
+- Bumped RevealJS' version to 5.2 to allow video playing in speaker view.
+  [#536](https://github.com/jeertmans/manim-slides/pull/536)
+
+(v5.4.2)=
+## [v5.4.2](https://github.com/jeertmans/manim-slides/compare/v5.4.1...v5.4.2)
+
+(v5.4.2-fixed)=
+### Fixed
+
+- Fixed `start_skip_animations` to actually pass argument to ManimCE,
+  otherwise video animations were still rendered, just excluded from
+  the final output.
+  [#524](https://github.com/jeertmans/manim-slides/pull/524)
+
+(v5.4.1)=
+## [v5.4.1](https://github.com/jeertmans/manim-slides/compare/v5.4.0...v5.4.1)
+
+(v5.4.1-added)=
+### Added
+
+- Added `start_skip_animations` and `stop_skip_animations` methods.
+  [#523](https://github.com/jeertmans/manim-slides/pull/523)
+
+(v5.4.0)=
+## [v5.4.0](https://github.com/jeertmans/manim-slides/compare/v5.3.1...v5.4.0)
+
+(v5.4.0-added)=
+### Added
+
+- Added `skip_animations` compatibility with ManimCE.
+  [@Rapsssito](https://github.com/Rapsssito) [#516](https://github.com/jeertmans/manim-slides/pull/516)
+
+(v5.4.0-chore)=
+### Chore
+
+- Bumped Manim to `>=0.19`, as it fixed OpenGL renderer issue.
+  [#522](https://github.com/jeertmans/manim-slides/pull/522)
+
+(v5.4.0-fixed)=
+### Fixed
+
+- Fixed OpenGL renderer having no partial movie files with Manim bindings.
+  [#522](https://github.com/jeertmans/manim-slides/pull/522)
+- Fixed `ConvertExample` example as `manim>=0.19` changed the `Code` class.
+  [#522](https://github.com/jeertmans/manim-slides/pull/522)
 
 (v5.3.1)=
 ## [v5.3.1](https://github.com/jeertmans/manim-slides/compare/v5.3.0...v5.3.1)
@@ -48,17 +146,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   was added to `manim-slides present` to force the info window.
   When there are multiple monitors, the info window will no longer
   be on the same monitor as the main window, unless overridden.
-  [@PeculiarProgrammer](https://github.com/PeculiarProgrammer)
+  [@taibeled](https://github.com/taibeled)
   [#482](https://github.com/jeertmans/manim-slides/pull/482)
 
 (v5.2.0-chore)=
 ### Chore
 
-- Bump ManimGL to `>=1.7.1`, to remove conflicting dependencies
+- Bumped ManimGL to `>=1.7.1`, to remove conflicting dependencies
   with Manim's.
   [#499](https://github.com/jeertmans/manim-slides/pull/499)
 
-- Bump ManimGL to `>=1.7.2`, to remove `pyrr` from dependencies,
+- Bumped ManimGL to `>=1.7.2`, to remove `pyrr` from dependencies,
   and to avoid complex code for supporting both `1.7.1` and `>=1.7.2`,
   as the latter includes many breaking changes.
   [#506](https://github.com/jeertmans/manim-slides/pull/506)
@@ -79,7 +177,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 (v5.1.10-changed)=
 ### Changed
 
-- Allow multiple slide reverses by going backward [@PeculiarProgrammer](https://github.com/PeculiarProgrammer).
+- Allow multiple slide reverses by going backward [@taibeled](https://github.com/taibeled).
   [#488](https://github.com/jeertmans/manim-slides/pull/488)
 
 (v5.1.10-fixed)=
@@ -121,7 +219,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 (v5.1.8-chore)=
 ### Chore
 
-- Pin `rtoml==0.9.0` on Windows platforms,
+- Pinned `rtoml==0.9.0` on Windows platforms,
   see [#398](https://github.com/jeertmans/manim-slides/pull/398),
   until
   [samuelcolvin/rtoml#74](https://github.com/samuelcolvin/rtoml/issues/74)
@@ -152,7 +250,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed whitespace issue in default RevealJS template.
   [#442](https://github.com/jeertmans/manim-slides/pull/442)
 - Fixed black screen issue on recent Qt versions and device loss detected,
-  thanks to [@PeculiarProgrammer](https://github.com/PeculiarProgrammer)!
+  thanks to [@taibeled](https://github.com/taibeled)!
   [#465](https://github.com/jeertmans/manim-slides/pull/465)
 
 (v5.1.8-removed)=

CITATION.cff

@@ -4,13 +4,14 @@
 cff-version: 1.2.0
 title: Manim Slides
 message: >-
-  If you use this software, please cite it using the
-  metadata from this file.
+  If you use this software, please cite it using our article
+  in the Journal of Open Source Education.
 type: software
 authors:
   - name: Jérome Eertmans
     orcid: 'https://orcid.org/0000-0002-5579-5360'
     website: 'https://eertmans.be'
+doi: 10.5281/zenodo.7971360
 repository-code: 'https://github.com/jeertmans/manim-slides'
 url: 'https://eertmans.be/manim-slides'
 abstract: >-
@@ -26,7 +27,7 @@ keywords:
   - PowerPoint
   - Python
 license: MIT
-version: v5.3.1
+version: v5.5.1
 preferred-citation:
   publisher:
     name: The Open Journal

README.md

@@ -1,9 +1,3 @@
-> [!IMPORTANT]
-> Take the [**Manim Slides Survey**](https://forms.gle/i4scrwPQghbTQwQs5)
-> to help improve this tool! Thanks in advance to all the people taking the time
-> to answer this short survey! The form is open until **January 31st 2025**,
-> and results will be communicated in the GitHub discussions.
-
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jeertmans/manim-slides/main/static/logo_dark_transparent.png">
   <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jeertmans/manim-slides/main/static/logo_light_transparent.png">
@@ -234,8 +228,8 @@ you can do so at: [jeertmans@icloud.com](mailto:jeertmans@icloud.com).
 [pypi-download-badge]: https://img.shields.io/pypi/dm/manim-slides
 [documentation-badge]: https://readthedocs.org/projects/manim-slides/badge/?version=latest
 [documentation-url]: https://manim-slides.readthedocs.io/
-[doi-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.8215167.svg
-[doi-url]: https://doi.org/10.5281/zenodo.8215167
+[doi-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.7971360.svg
+[doi-url]: https://doi.org/10.5281/zenodo.7971360
 [jose-badge]: https://jose.theoj.org/papers/10.21105/jose.00206/status.svg
 [jose-url]: https://doi.org/10.21105/jose.00206
 [codecov-badge]: https://codecov.io/gh/jeertmans/manim-slides/branch/main/graph/badge.svg?token=8P4DY9JCE4

docs/source/_static/template.html

@@ -18,82 +18,75 @@
   <body>
     <div class="reveal">
       <div class="slides">
-        {%- for presentation_config in presentation_configs -%}
-          {% set outer_loop = loop %}
-          {%- for slide_config in presentation_config.slides -%}
-            {%- if one_file -%}
+        {% for presentation_config in presentation_configs -%}
+          {%- set outer_loop = loop %}
+          {% for slide_config in presentation_config.slides %}
+            {% if one_file %}
               {% set file = file_to_data_uri(slide_config.file) %}
-            {%- else -%}
-              {% set file = assets_dir / slide_config.file.name %}
-            {%- endif -%}
-            <section
-              data-background-size={{ background_size }}
-              data-background-color="{{ presentation_config.background_color }}"
-              data-background-video="{{ file }}"
-              {% if loop.index == 1 and outer_loop.index == 1 -%}
-                data-background-video-muted
-              {%- endif %}
-              {% if slide_config.loop -%}
-                data-background-video-loop
-              {%- endif -%}
-              {% if slide_config.auto_next -%}
-                data-autoslide="{{ get_duration_ms(slide_config.file) }}"
-              {%- endif -%}>
-              {% if slide_config.notes != "" -%}
-                <aside class="notes" data-markdown>{{ slide_config.notes }}</aside>
-              {%- endif %}
-            </section>
-          {%- endfor -%}
-        {%- endfor -%}
+            {% else %}
+              {% set file = assets_dir / (prefix(outer_loop.index0) + slide_config.file.name) %}
+            {% endif %}
+        <section
+          data-background-size={{ background_size }}
+          data-background-color="{{ presentation_config.background_color }}"
+          data-background-video="{{ file }}"
+          {% if loop.index == 1 and outer_loop.index == 1 %}
+          data-background-video-muted
+          {% endif %}
+          {% if slide_config.loop %}
+          data-background-video-loop
+          {% endif %}
+          {% if slide_config.auto_next %}
+          data-autoslide="{{ get_duration_ms(slide_config.file) }}"
+          {% endif %}
+          >
+          {% if slide_config.notes != "" %}
+            <aside class="notes" data-markdown>{{ slide_config.notes }}</aside>
+          {% endif %}
+        </section>
+          {% endfor %}
+        {% endfor %}
       </div>
     </div>
 
     <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/reveal.min.js"></script>
 
     <!-- To include plugins, see: https://revealjs.com/plugins/ -->
-
-    {% if has_notes -%}
+    {% if has_notes %}
       <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/plugin/markdown/markdown.min.js"></script>
       <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/plugin/notes/notes.min.js"></script>
-    {%- endif -%}
+    {% endif %}
 
     <!-- <script src="index.js"></script> -->
     <script>
       Reveal.initialize({
-        {% if has_notes -%}
-          plugins: [ RevealMarkdown, RevealNotes ],
-        {%- endif %}
+        {% if has_notes %}
+        /// The list of RevealJS plugins.
+        plugins: [ RevealMarkdown, RevealNotes ],
+        {% endif %}
         // The "normal" size of the presentation, aspect ratio will
         // be preserved when the presentation is scaled to fit different
         // resolutions. Can be specified using percentage units.
         width: {{ width }},
         height: {{ height }},
-
         // Factor of the display size that should remain empty around
         // the content
         margin: {{ margin }},
-
         // Bounds for smallest/largest possible scale to apply to content
         minScale: {{ min_scale }},
         maxScale: {{ max_scale }},
-
         // Display presentation control arrows
         controls: {{ controls }},
-
         // Help the user learn the controls by providing hints, for example by
         // bouncing the down arrow when they first encounter a vertical slide
         controlsTutorial: {{ controls_tutorial }},
-
         // Determines where controls appear, "edges" or "bottom-right"
         controlsLayout: {{ controls_layout }},
-
         // Visibility rule for backwards navigation arrows; "faded", "hidden"
         // or "visible"
         controlsBackArrows: {{ controls_back_arrows }},
-
         // Display a presentation progress bar
         progress: {{ progress }},
-
         // Display the page number of the current slide
         // - true:    Show slide number
         // - false:   Hide slide number
@@ -109,55 +102,43 @@
         // object and return an array with one string [slideNumber] or
         // three strings [n1,delimiter,n2]. See #formatSlideNumber().
         slideNumber: {{ slide_number }},
-
         // Can be used to limit the contexts in which the slide number appears
         // - "all":      Always show the slide number
         // - "print":    Only when printing to PDF
         // - "speaker":  Only in the speaker view
         showSlideNumber: {{ show_slide_number }},
-
         // Use 1 based indexing for # links to match slide number (default is zero
         // based)
         hashOneBasedIndex: {{ hash_one_based_index }},
-
         // Add the current slide number to the URL hash so that reloading the
         // page/copying the URL will return you to the same slide
         hash: {{ hash }},
-
         // Flags if we should monitor the hash and change slides accordingly
         respondToHashChanges: {{ respond_to_hash_changes }},
-
+        // Enable support for jump-to-slide navigation shortcuts
+        jumpToSlide: {{ jump_to_slide }},
         // Push each slide change to the browser history.  Implies `hash: true`
         history: {{ history }},
-
         // Enable keyboard shortcuts for navigation
         keyboard: {{ keyboard }},
-
         // Optional function that blocks keyboard events when retuning false
         //
         // If you set this to 'focused', we will only capture keyboard events
         // for embedded decks when they are in focus
         keyboardCondition: {{ keyboard_condition }},
-
         // Disables the default reveal.js slide layout (scaling and centering)
         // so that you can use custom CSS layout
         disableLayout: {{ disable_layout }},
-
         // Enable the slide overview mode
         overview: {{ overview }},
-
         // Vertical centering of slides
         center: {{ center }},
-
         // Enables touch navigation on devices with touch input
         touch: {{ touch }},
-
         // Loop the presentation
         loop: {{ loop }},
-
         // Change the presentation direction to be RTL
         rtl: {{ rtl }},
-
         // Changes the behavior of our navigation directions.
         //
         // "default"
@@ -183,138 +164,104 @@
         // from 1.3 -> 2.1. If "grid" is used, the same navigation takes you
         // from 1.3 -> 2.3.
         navigationMode: {{ navigation_mode }},
-
         // Randomizes the order of slides each time the presentation loads
         shuffle: {{ shuffle }},
-
         // Turns fragments on and off globally
         fragments: {{ fragments }},
-
         // Flags whether to include the current fragment in the URL,
         // so that reloading brings you to the same fragment position
         fragmentInURL: {{ fragment_in_url }},
-
         // Flags if the presentation is running in an embedded mode,
         // i.e. contained within a limited portion of the screen
         embedded: {{ embedded }},
-
         // Flags if we should show a help overlay when the question-mark
         // key is pressed
         help: {{ help }},
-
         // Flags if it should be possible to pause the presentation (blackout)
         pause: {{ pause }},
-
         // Flags if speaker notes should be visible to all viewers
         showNotes: {{ show_notes }},
-
         // Global override for autolaying embedded media (video/audio/iframe)
         // - null:   Media will only autoplay if data-autoplay is present
         // - true:   All media will autoplay, regardless of individual setting
         // - false:  No media will autoplay, regardless of individual setting
         autoPlayMedia: {{ auto_play_media }},
-
         // Global override for preloading lazy-loaded iframes
         // - null:   Iframes with data-src AND data-preload will be loaded when within
         //           the viewDistance, iframes with only data-src will be loaded when visible
         // - true:   All iframes with data-src will be loaded when within the viewDistance
         // - false:  All iframes with data-src will be loaded only when visible
         preloadIframes: {{ preload_iframes }},
-
         // Can be used to globally disable auto-animation
         autoAnimate: {{ auto_animate }},
-
         // Optionally provide a custom element matcher that will be
         // used to dictate which elements we can animate between.
         autoAnimateMatcher: {{ auto_animate_matcher }},
-
         // Default settings for our auto-animate transitions, can be
         // overridden per-slide or per-element via data arguments
         autoAnimateEasing: {{ auto_animate_easing }},
         autoAnimateDuration: {{ auto_animate_duration }},
         autoAnimateUnmatched: {{ auto_animate_unmatched }},
-
         // CSS properties that can be auto-animated. Position & scale
         // is matched separately so there's no need to include styles
         // like top/right/bottom/left, width/height or margin.
         autoAnimateStyles: {{ auto_animate_styles }},
-
         // Controls automatic progression to the next slide
         // - 0:      Auto-sliding only happens if the data-autoslide HTML attribute
         //           is present on the current slide or fragment
         // - 1+:     All slides will progress automatically at the given interval
         // - false:  No auto-sliding, even if data-autoslide is present
         autoSlide: {{ auto_slide }},
-
         // Stop auto-sliding after user input
         autoSlideStoppable: {{ auto_slide_stoppable }},
-
         // Use this method for navigation when auto-sliding (defaults to navigateNext)
         autoSlideMethod: {{ auto_slide_method }},
-
         // Specify the average time in seconds that you think you will spend
         // presenting each slide. This is used to show a pacing timer in the
         // speaker view
         defaultTiming: {{ default_timing }},
-
         // Enable slide navigation via mouse wheel
         mouseWheel: {{ mouse_wheel }},
-
         // Opens links in an iframe preview overlay
         // Add `data-preview-link` and `data-preview-link="false"` to customize each link
         // individually
         previewLinks: {{ preview_links }},
-
         // Exposes the reveal.js API through window.postMessage
         postMessage: {{ post_message }},
-
         // Dispatches all reveal.js events to the parent window through postMessage
         postMessageEvents: {{ post_message_events }},
-
         // Focuses body when page changes visibility to ensure keyboard shortcuts work
         focusBodyOnPageVisibilityChange: {{ focus_body_on_page_visibility_change }},
-
         // Transition style
         transition: {{ transition }}, // none/fade/slide/convex/concave/zoom
-
         // Transition speed
         transitionSpeed: {{ transition_speed }}, // default/fast/slow
-
         // Transition style for full page slide backgrounds
         backgroundTransition: {{ background_transition }}, // none/fade/slide/convex/concave/zoom
-
         // The maximum number of pages a single slide can expand onto when printing
         // to PDF, unlimited by default
         pdfMaxPagesPerSlide: {{ pdf_max_pages_per_slide }},
-
         // Prints each fragment on a separate slide
         pdfSeparateFragments: {{ pdf_separate_fragments }},
-
         // Offset used to reduce the height of content within exported PDF pages.
         // This exists to account for environment differences based on how you
         // print to PDF. CLI printing options, like phantomjs and wkpdf, can end
         // on precisely the total height of the document whereas in-browser
         // printing has to end one pixel before.
         pdfPageHeightOffset: {{ pdf_page_height_offset }},
-
         // Number of slides away from the current that are visible
         viewDistance: {{ view_distance }},
-
         // Number of slides away from the current that are visible on mobile
         // devices. It is advisable to set this to a lower number than
         // viewDistance in order to save resources.
         mobileViewDistance: {{ mobile_view_distance }},
-
         // The display mode that will be used to show slides
         display: {{ display }},
-
         // Hide cursor if inactive
         hideInactiveCursor: {{ hide_inactive_cursor }},
-
         // Time before the cursor is hidden (in ms)
         hideCursorTime: {{ hide_cursor_time }}
       });
-
       {% if one_file %}
       // Fix found by @t-fritsch and @Rapsssito on GitHub
       // see: https://github.com/hakimel/reveal.js/discussions/3362#discussioncomment-11733074.

docs/source/conf.py

@@ -4,6 +4,7 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
 import sys
 from datetime import date
 
@@ -36,7 +37,7 @@ extensions = [
     "sphinx_copybutton",
     "sphinx_design",
     # Custom
-    "manim_slides.docs.manim_slides_directive",
+    "manim_slides.sphinxext.manim_slides_directive",
 ]
 
 autodoc_typehints = "both"
@@ -55,6 +56,7 @@ add_module_names = False
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
 html_theme = "furo"
 html_static_path = ["_static"]
 html_favicon = "_static/favicon.png"

docs/source/contributing/workflow.md

@@ -32,7 +32,7 @@ and development dependencies. If not already, please install this tool.
 With uv, installation becomes straightforward:
 
 ```bash
-uv sync --all-extras
+uv sync
 ```
 
 :::{note}

docs/source/faq.md

@@ -92,7 +92,7 @@ This will also show the default value for each option.
 If you want to create your own template, the best is to start from the default one.
 
 You can either download it from the
-[template folder](https://github.com/jeertmans/manim-slides/tree/main/manim_slides/templates)
+[template folder](https://github.com/jeertmans/manim-slides/tree/main/manim_slides/cli/convert/templates)
 or use the `manim-slides convert --to=FORMAT --show-template` command,
 where `FORMAT` is one of the supported formats.
 

docs/source/features_table.md

@@ -10,20 +10,22 @@ The following summarizes the different presentation features Manim Slides offers
 | :--- | :---: | :---: | :---: | :---: |
 | Basic navigation through slides | Yes | Yes | Yes | Yes (static image) |
 | Replay slide | Yes | No | No | N/A |
-| Pause animation | Yes | No | No | N/A |
+| Pause animation | Yes | Yes | No | N/A |
 | Play slide in reverse | Yes | No | No | N/A |
 | Slide count | Yes | Yes (optional) | Yes (optional) | N/A |
 | Needs Python with Manim Slides installed | Yes | No | No | No
-| Requires internet access | No | Yes | No | No |
+| Requires internet access | No | Depends[^1] | No | No |
 | Auto. play slides | Yes | Yes | Yes | N/A |
 | Loops support | Yes | Yes | Yes | N/A |
 | Fully customizable | No | Yes (`--use-template` option) | No | No |
-| Other dependencies | None | A modern web browser | PowerPoint or LibreOffice Impress[^1] | None |
-| Works cross-platforms | Yes | Yes | Partly[^1][^2] | Yes |
+| Other dependencies | None | A modern web browser | PowerPoint or LibreOffice Impress[^2] | None |
+| Works cross-platforms | Yes | Yes | Partly[^2][^3] | Yes |
 :::
 
-[^1]: If you encounter a problem where slides do not automatically play or loops do not work,
+[^1]: By default, HTML assets are loaded from the internet, but they can be
+  pre-downloaded and embedded in the HTML file at conversion time.
+[^2]: If you encounter a problem where slides do not automatically play or loops do not work,
   please
   [file an issue on GitHub](https://github.com/jeertmans/manim-slides/issues/new/choose).
-[^2]: PowerPoint online does not seem to support automatic playing of videos,
+[^3]: PowerPoint online does not seem to support automatic playing of videos,
   so you need LibreOffice Impress on Linux platforms.

docs/source/reference/api.md

@@ -18,6 +18,8 @@ use, not the methods used internally when rendering.
         next_section,
         next_slide,
         remove_from_canvas,
+        start_skip_animations,
+        stop_skip_animations,
         wait_time_between_slides,
         wipe,
         zoom,

docs/source/reference/cli.md

@@ -4,7 +4,7 @@ This page contains an exhaustive list of all the commands available with `manim-
 
 
 ```{eval-rst}
-.. click:: manim_slides.__main__:cli
+.. click:: manim_slides.cli.commands:main
     :prog: manim-slides
     :nested: full
 ```

docs/source/reference/customize_html.md

@@ -4,7 +4,7 @@ One of the benefits of the `convert` command is the use of template files.
 
 Currently, only the HTML export uses one. If not specified, the template
 will be the one shipped with Manim Slides, see
-[`manim_slides/templates/revealjs.html`](https://github.com/jeertmans/manim-slides/blob/main/manim_slides/templates/revealjs.html).
+[`manim_slides/cli/convert/templates/revealjs.html`](https://github.com/jeertmans/manim-slides/blob/main/manim_slides/cli/convert/templates/revealjs.html).
 
 Because you can actually use your own template with  the `--use-template`
 option, possibilities are infinite!

docs/source/reference/html.md

@@ -30,7 +30,7 @@ manim-slides convert --show-config
 ## Using a Custom Template
 
 The default template used for HTML conversion can be found on
-[GitHub](https://github.com/jeertmans/manim-slides/blob/main/manim_slides/templates/revealjs.html)
+[GitHub](https://github.com/jeertmans/manim-slides/blob/main/manim_slides/cli/convert/templates/revealjs.html)
 or printed with the `--show-template` option.
 If you wish to use another template, you can do so with the
 `--use-template FILE` option.

docs/source/reference/sphinx_extension.md

@@ -1,6 +1,6 @@
 # Manim Slides' Sphinx directive
 
 ```{eval-rst}
-.. automodule:: manim_slides.docs.manim_slides_directive
+.. automodule:: manim_slides.sphinxext.manim_slides_directive
    :members: ManimSlidesDirective
 ```

example.py

@@ -53,7 +53,7 @@ class ConvertExample(Slide):
         self.next_slide()
 
         code = Code(
-            code="""from manim import *
+            code_string="""from manim import *
 
 
 class Example(Scene):
@@ -72,7 +72,7 @@ class Example(Scene):
         )
 
         code_step_1 = Code(
-            code="""from manim import *
+            code_string="""from manim import *
 from manim_slides import Slide
 
 class Example(Scene):
@@ -91,7 +91,7 @@ class Example(Scene):
         )
 
         code_step_2 = Code(
-            code="""from manim import *
+            code_string="""from manim import *
 from manim_slides import Slide
 
 class Example(Slide):
@@ -110,7 +110,7 @@ class Example(Slide):
         )
 
         code_step_3 = Code(
-            code="""from manim import *
+            code_string="""from manim import *
 from manim_slides import Slide
 
 class Example(Slide):
@@ -129,7 +129,7 @@ class Example(Slide):
         )
 
         code_step_4 = Code(
-            code="""from manim import *
+            code_string="""from manim import *
 from manim_slides import Slide
 
 class Example(Slide):
@@ -148,19 +148,19 @@ class Example(Slide):
         )
 
         code_step_5 = Code(
-            code="manim-slide render example.py Example",
+            code_string="manim-slide render example.py Example",
             language="console",
         )
 
         code_step_6 = Code(
-            code="manim-slides Example",
+            code_string="manim-slides Example",
             language="console",
         )
 
         or_text = Text("or generate HTML presentation").scale(0.5)
 
         code_step_7 = Code(
-            code="manim-slides convert Example slides.html --open",
+            code_string="manim-slides convert Example slides.html --open",
             language="console",
         ).shift(DOWN)
 

manim_slides/__init__.py

@@ -1,3 +1,10 @@
+"""
+Manim Slides module.
+
+Submodules are lazily imported, in order to provide a faster import experience
+in some cases.
+"""
+
 import sys
 from types import ModuleType
 from typing import Any
@@ -8,9 +15,7 @@ from .__version__ import __version__
 class Module(ModuleType):
     def __getattr__(self, name: str) -> Any:
         if name == "Slide" or name == "ThreeDSlide":
-            module = __import__(
-                "manim_slides.slide", None, None, ["Slide", "ThreeDSlide"]
-            )
+            module = __import__("manim_slides.slide", None, None, [name])
             return getattr(module, name)
         elif name == "ManimSlidesMagic":
             module = __import__(

manim_slides/__main__.py

@@ -1,11 +1,8 @@
-import json
-
-import click
-import requests
-from click_default_group import DefaultGroup
+"""Manim Slides' main entrypoint."""
 
 from .__version__ import __version__
 from .checkhealth import checkhealth
+from .cli.commands import main
 from .convert import convert
 from .logger import logger
 from .present import list_scenes, present
@@ -72,4 +69,4 @@ cli.add_command(render)
 cli.add_command(wizard)
 
 if __name__ == "__main__":
-    cli()
+    main()

manim_slides/__version__.py

@@ -1 +1,3 @@
-__version__ = "5.3.1"
+"""Manim Slides' version."""
+
+__version__ = "5.4.2"

manim_slides/cli/commands.py

@@ -0,0 +1,72 @@
+"""Manim Slides' CLI."""
+
+import json
+
+import click
+import requests
+from click_default_group import DefaultGroup
+
+from ..__version__ import __version__
+from ..core.logger import logger
+from .convert.commands import convert
+from .present.commands import list_scenes, present
+from .render.commands import render
+from .wizard.commands import init, wizard
+
+
+@click.group(cls=DefaultGroup, default="present", default_if_no_args=True)
+@click.option(
+    "--notify-outdated-version/--silent",
+    " /-S",
+    is_flag=True,
+    default=True,
+    help="Check if a new version of Manim Slides is available.",
+)
+@click.version_option(__version__, "-v", "--version")
+@click.help_option("-h", "--help")
+def main(notify_outdated_version: bool) -> None:
+    """
+    Manim Slides command-line utilities.
+
+    If no command is specified, defaults to `present`.
+    """
+    # Code below is mostly a copy from:
+    # https://github.com/ManimCommunity/manim/blob/main/manim/cli/render/commands.py
+    if notify_outdated_version:
+        manim_info_url = "https://pypi.org/pypi/manim-slides/json"
+        warn_prompt = "Cannot check if latest release of Manim Slides is installed"
+        try:
+            req_info: requests.models.Response = requests.get(manim_info_url, timeout=2)
+            req_info.raise_for_status()
+            stable = req_info.json()["info"]["version"]
+            if stable != __version__:
+                click.echo(
+                    "You are using Manim Slides version "
+                    + click.style(f"v{__version__}", fg="red")
+                    + ", but version "
+                    + click.style(f"v{stable}", fg="green")
+                    + " is available."
+                )
+                click.echo(
+                    "You should consider upgrading via "
+                    + click.style("pip install -U manim-slides", fg="yellow")
+                )
+        except requests.exceptions.HTTPError:
+            logger.debug(f"HTTP Error: {warn_prompt}")
+        except requests.exceptions.ConnectionError:
+            logger.debug(f"Connection Error: {warn_prompt}")
+        except requests.exceptions.Timeout:
+            logger.debug(f"Timed Out: {warn_prompt}")
+        except json.JSONDecodeError:
+            logger.debug(warn_prompt)
+            logger.debug(f"Error decoding JSON from {manim_info_url}")
+        except Exception:
+            logger.debug(f"Something went wrong: {warn_prompt}")
+
+
+main.add_command(convert)
+main.add_command(init)
+main.add_command(list_scenes)
+main.add_command(present)
+main.add_command(render)
+main.add_command(wizard)

manim_slides/cli/commons.py

@@ -4,8 +4,9 @@ from typing import Any, Callable
 import click
 from click import Context, Parameter
 
-from .defaults import CONFIG_PATH, FOLDER_PATH
-from .logger import logger
+from ..core.config import list_presentation_configs
+from ..core.defaults import CONFIG_PATH, FOLDER_PATH
+from ..core.logger import logger
 
 F = Callable[..., Any]
 Wrapper = Callable[[F], F]
@@ -88,6 +89,68 @@ def folder_path_option(function: F) -> F:
         callback=callback,
         help="Set slides folder.",
         show_default=True,
+        is_eager=True,  # Needed to expose its value to other callbacks
     )
 
     return wrapper(function)
+
+
+def scenes_argument(function: F) -> F:
+    """
+    Wrap a function to add a scenes arguments.
+
+    This function assumes that :func:`folder_path_option` is also used
+    on the same decorated function.
+    """
+
+    def callback(ctx: Context, param: Parameter, value: tuple[str]) -> list[Path]:
+        folder: Path = ctx.params.get("folder")
+
+        presentation_config_paths = list_presentation_configs(folder)
+        scene_names = [path.stem for path in presentation_config_paths]
+        num_scenes = len(scene_names)
+        num_digits = len(str(num_scenes))
+
+        if num_scenes == 0:
+            raise click.UsageError(
+                f"Folder {folder} does not contain "
+                "any valid config file, did you render the animations first?"
+            )
+
+        paths = []
+
+        if value:
+            for scene_name in value:
+                try:
+                    i = scene_names.index(scene_name)
+                    paths.append(presentation_config_paths[i])
+                except ValueError:
+                    raise click.UsageError(
+                        f"Could not find scene `{scene_name}` in: "
+                        + ", ".join(scene_names)
+                        + ". Did you make a typo or forgot to render the animations first?"
+                    ) from None
+        else:
+            click.echo(
+                "Choose at least one or more scenes from "
+                "(enter the corresponding number):\n"
+                + "\n".join(
+                    f"- {i:{num_digits}d}: {name}"
+                    for i, name in enumerate(scene_names, start=1)
+                )
+            )
+            continue_prompt = True
+            while continue_prompt:
+                index = click.prompt(
+                    "Please enter a value", type=click.IntRange(1, num_scenes)
+                )
+                paths.append(presentation_config_paths[index - 1])
+                continue_prompt = click.confirm(
+                    "Do you want to enter an additional scene?"
+                )
+
+        return paths
+
+    wrapper: Wrapper = click.argument("scenes", nargs=-1, callback=callback)
+
+    return wrapper(function)

manim_slides/cli/convert/commands.py

@@ -37,14 +37,18 @@ from pydantic_core import CoreSchema, core_schema
 from pydantic_extra_types.color import Color
 from tqdm import tqdm
 
+from ...core.config import PresentationConfig
+from ...core.logger import logger
+from ..commons import folder_path_option, scenes_argument, verbosity_option
 from . import templates
-from .commons import folder_path_option, verbosity_option
-from .config import PresentationConfig
-from .logger import logger
-from .present import get_scenes_presentation_config
 
 
 def open_with_default(file: Path) -> None:
+    """
+    Open a file with the default application.
+
+    :param file: The file to open.
+    """
     system = platform.system()
     if system == "Darwin":
         subprocess.call(("open", str(file)))
@@ -142,6 +146,7 @@ class Str(str):
 
     # This fixes pickling issue on Python 3.8
     __reduce_ex__ = str.__reduce_ex__
+    # TODO: do we still need this?
 
     @classmethod
     def __get_pydantic_core_schema__(
@@ -531,7 +536,7 @@ class RevealJS(Converter):
         "black",
         description="Background color used in slides, not relevant if videos fill the whole area.",
     )
-    reveal_version: str = Field("5.1.0", description="RevealJS version.")
+    reveal_version: str = Field("5.2.0", description="RevealJS version.")
     reveal_theme: RevealTheme = Field(
         RevealTheme.black, description="RevealJS version."
     )
@@ -547,6 +552,11 @@ class RevealJS(Converter):
         return resources.files(templates).joinpath("revealjs.html").read_text()
 
     def open(self, file: Path) -> None:
+        """
+        Open the HTML file inside a web browser.
+
+        :param path: The path to the HTML file.
+        """
         webbrowser.open(file.absolute().as_uri())
 
     def convert_to(self, dest: Path) -> None:  # noqa: C901
@@ -594,7 +604,9 @@ class RevealJS(Converter):
         dest.parent.mkdir(parents=True, exist_ok=True)
 
         with open(dest, "w") as f:
-            revealjs_template = Template(self.load_template())
+            revealjs_template = Template(
+                self.load_template(), trim_blocks=True, lstrip_blocks=True
+            )
 
             options = self.model_dump()
 
@@ -908,7 +920,7 @@ def show_template_option(function: Callable[..., Any]) -> Callable[..., Any]:
 
 
 @click.command()
-@click.argument("scenes", nargs=-1)
+@scenes_argument
 @folder_path_option
 @click.argument("dest", type=click.Path(dir_okay=False, path_type=Path))
 @click.option(
@@ -958,7 +970,7 @@ def show_template_option(function: Callable[..., Any]) -> Callable[..., Any]:
 @show_config_options
 @verbosity_option
 def convert(
-    scenes: list[str],
+    scenes: list[Path],
     folder: Path,
     dest: Path,
     to: str,
@@ -969,7 +981,7 @@ def convert(
     one_file: bool,
 ) -> None:
     """Convert SCENE(s) into a given format and writes the result in DEST."""
-    presentation_configs = get_scenes_presentation_config(scenes, folder)
+    presentation_configs = [PresentationConfig.from_file(scene) for scene in scenes]
 
     try:
         if to == "auto":

manim_slides/cli/convert/templates/__init__.py

@@ -0,0 +1 @@
+"""Manim Slides conversion templates."""

manim_slides/cli/convert/templates/revealjs.html

@@ -12,7 +12,6 @@
     <!-- Theme used for syntax highlighting of code -->
     <!-- <link rel="stylesheet" href="lib/css/zenburn.css"> -->
     <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/zenburn.min.css">
-
     <!-- <link rel="stylesheet" href="index.css"> -->
   </head>
 
@@ -20,82 +19,74 @@
     <div class="reveal">
       <div class="slides">
         {% for presentation_config in presentation_configs -%}
-          {% set outer_loop = loop %}
-          {%- for slide_config in presentation_config.slides -%}
-            {%- if one_file -%}
+          {%- set outer_loop = loop %}
+          {% for slide_config in presentation_config.slides %}
+            {% if one_file %}
               {% set file = file_to_data_uri(slide_config.file) %}
-            {%- else -%}
+            {% else %}
               {% set file = assets_dir / (prefix(outer_loop.index0) + slide_config.file.name) %}
-            {%- endif -%}
+            {% endif %}
         <section
           data-background-size={{ background_size }}
           data-background-color="{{ presentation_config.background_color }}"
           data-background-video="{{ file }}"
-          {% if loop.index == 1 and outer_loop.index == 1 -%}
-            data-background-video-muted
-          {%- endif -%}
-          {% if slide_config.loop -%}
-            data-background-video-loop
-          {%- endif -%}
-          {% if slide_config.auto_next -%}
-            data-autoslide="{{ get_duration_ms(slide_config.file) }}"
-          {%- endif %}
+          {% if loop.index == 1 and outer_loop.index == 1 %}
+          data-background-video-muted
+          {% endif %}
+          {% if slide_config.loop %}
+          data-background-video-loop
+          {% endif %}
+          {% if slide_config.auto_next %}
+          data-autoslide="{{ get_duration_ms(slide_config.file) }}"
+          {% endif %}
           >
-          {%- if slide_config.notes != "" -%}
+          {% if slide_config.notes != "" %}
             <aside class="notes" data-markdown>{{ slide_config.notes }}</aside>
-          {%- endif %}
+          {% endif %}
         </section>
-          {%- endfor -%}
-        {%- endfor -%}
+          {% endfor %}
+        {% endfor %}
       </div>
     </div>
 
     <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/reveal.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/plugin/notes/notes.min.js"></script>
 
     <!-- To include plugins, see: https://revealjs.com/plugins/ -->
-
-    {% if has_notes -%}
-      <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/plugin/markdown/markdown.min.js"></script>
-      <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/plugin/notes/notes.min.js"></script>
-    {%- endif -%}
+    {% if has_notes %}
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/reveal.js/{{ reveal_version }}/plugin/markdown/markdown.min.js"></script>
+    {% endif %}
 
     <!-- <script src="index.js"></script> -->
     <script>
       Reveal.initialize({
-        {% if has_notes -%}
-          plugins: [ RevealMarkdown, RevealNotes ],
-        {%- endif %}
+        {% if has_notes %}
+        /// The list of RevealJS plugins.
+        plugins: [ RevealMarkdown, RevealNotes ],
+        {% endif %}
         // The "normal" size of the presentation, aspect ratio will
         // be preserved when the presentation is scaled to fit different
         // resolutions. Can be specified using percentage units.
         width: {{ width }},
         height: {{ height }},
-
         // Factor of the display size that should remain empty around
         // the content
         margin: {{ margin }},
-
         // Bounds for smallest/largest possible scale to apply to content
         minScale: {{ min_scale }},
         maxScale: {{ max_scale }},
-
         // Display presentation control arrows
         controls: {{ controls }},
-
         // Help the user learn the controls by providing hints, for example by
         // bouncing the down arrow when they first encounter a vertical slide
         controlsTutorial: {{ controls_tutorial }},
-
         // Determines where controls appear, "edges" or "bottom-right"
         controlsLayout: {{ controls_layout }},
-
         // Visibility rule for backwards navigation arrows; "faded", "hidden"
         // or "visible"
         controlsBackArrows: {{ controls_back_arrows }},
-
         // Display a presentation progress bar
         progress: {{ progress }},
-
         // Display the page number of the current slide
         // - true:    Show slide number
         // - false:   Hide slide number
@@ -111,58 +102,43 @@
         // object and return an array with one string [slideNumber] or
         // three strings [n1,delimiter,n2]. See #formatSlideNumber().
         slideNumber: {{ slide_number }},
-
         // Can be used to limit the contexts in which the slide number appears
         // - "all":      Always show the slide number
         // - "print":    Only when printing to PDF
         // - "speaker":  Only in the speaker view
         showSlideNumber: {{ show_slide_number }},
-
         // Use 1 based indexing for # links to match slide number (default is zero
         // based)
         hashOneBasedIndex: {{ hash_one_based_index }},
-
         // Add the current slide number to the URL hash so that reloading the
         // page/copying the URL will return you to the same slide
         hash: {{ hash }},
-
         // Flags if we should monitor the hash and change slides accordingly
         respondToHashChanges: {{ respond_to_hash_changes }},
-
         // Enable support for jump-to-slide navigation shortcuts
         jumpToSlide: {{ jump_to_slide }},
-
         // Push each slide change to the browser history.  Implies `hash: true`
         history: {{ history }},
-
         // Enable keyboard shortcuts for navigation
         keyboard: {{ keyboard }},
-
         // Optional function that blocks keyboard events when retuning false
         //
         // If you set this to 'focused', we will only capture keyboard events
         // for embedded decks when they are in focus
         keyboardCondition: {{ keyboard_condition }},
-
         // Disables the default reveal.js slide layout (scaling and centering)
         // so that you can use custom CSS layout
         disableLayout: {{ disable_layout }},
-
         // Enable the slide overview mode
         overview: {{ overview }},
-
         // Vertical centering of slides
         center: {{ center }},
-
         // Enables touch navigation on devices with touch input
         touch: {{ touch }},
-
         // Loop the presentation
         loop: {{ loop }},
-
         // Change the presentation direction to be RTL
         rtl: {{ rtl }},
-
         // Changes the behavior of our navigation directions.
         //
         // "default"
@@ -188,139 +164,122 @@
         // from 1.3 -> 2.1. If "grid" is used, the same navigation takes you
         // from 1.3 -> 2.3.
         navigationMode: {{ navigation_mode }},
-
         // Randomizes the order of slides each time the presentation loads
         shuffle: {{ shuffle }},
-
         // Turns fragments on and off globally
         fragments: {{ fragments }},
-
         // Flags whether to include the current fragment in the URL,
         // so that reloading brings you to the same fragment position
         fragmentInURL: {{ fragment_in_url }},
-
         // Flags if the presentation is running in an embedded mode,
         // i.e. contained within a limited portion of the screen
         embedded: {{ embedded }},
-
         // Flags if we should show a help overlay when the question-mark
         // key is pressed
         help: {{ help }},
-
         // Flags if it should be possible to pause the presentation (blackout)
         pause: {{ pause }},
-
         // Flags if speaker notes should be visible to all viewers
         showNotes: {{ show_notes }},
-
         // Global override for autolaying embedded media (video/audio/iframe)
         // - null:   Media will only autoplay if data-autoplay is present
         // - true:   All media will autoplay, regardless of individual setting
         // - false:  No media will autoplay, regardless of individual setting
         autoPlayMedia: {{ auto_play_media }},
-
         // Global override for preloading lazy-loaded iframes
         // - null:   Iframes with data-src AND data-preload will be loaded when within
         //           the viewDistance, iframes with only data-src will be loaded when visible
         // - true:   All iframes with data-src will be loaded when within the viewDistance
         // - false:  All iframes with data-src will be loaded only when visible
         preloadIframes: {{ preload_iframes }},
-
         // Can be used to globally disable auto-animation
         autoAnimate: {{ auto_animate }},
-
         // Optionally provide a custom element matcher that will be
         // used to dictate which elements we can animate between.
         autoAnimateMatcher: {{ auto_animate_matcher }},
-
         // Default settings for our auto-animate transitions, can be
         // overridden per-slide or per-element via data arguments
         autoAnimateEasing: {{ auto_animate_easing }},
         autoAnimateDuration: {{ auto_animate_duration }},
         autoAnimateUnmatched: {{ auto_animate_unmatched }},
-
         // CSS properties that can be auto-animated. Position & scale
         // is matched separately so there's no need to include styles
         // like top/right/bottom/left, width/height or margin.
         autoAnimateStyles: {{ auto_animate_styles }},
-
         // Controls automatic progression to the next slide
         // - 0:      Auto-sliding only happens if the data-autoslide HTML attribute
         //           is present on the current slide or fragment
         // - 1+:     All slides will progress automatically at the given interval
         // - false:  No auto-sliding, even if data-autoslide is present
         autoSlide: {{ auto_slide }},
-
         // Stop auto-sliding after user input
         autoSlideStoppable: {{ auto_slide_stoppable }},
-
         // Use this method for navigation when auto-sliding (defaults to navigateNext)
         autoSlideMethod: {{ auto_slide_method }},
-
         // Specify the average time in seconds that you think you will spend
         // presenting each slide. This is used to show a pacing timer in the
         // speaker view
         defaultTiming: {{ default_timing }},
-
         // Enable slide navigation via mouse wheel
         mouseWheel: {{ mouse_wheel }},
-
         // Opens links in an iframe preview overlay
         // Add `data-preview-link` and `data-preview-link="false"` to customize each link
         // individually
         previewLinks: {{ preview_links }},
-
         // Exposes the reveal.js API through window.postMessage
         postMessage: {{ post_message }},
-
         // Dispatches all reveal.js events to the parent window through postMessage
         postMessageEvents: {{ post_message_events }},
-
         // Focuses body when page changes visibility to ensure keyboard shortcuts work
         focusBodyOnPageVisibilityChange: {{ focus_body_on_page_visibility_change }},
-
         // Transition style
         transition: {{ transition }}, // none/fade/slide/convex/concave/zoom
-
         // Transition speed
         transitionSpeed: {{ transition_speed }}, // default/fast/slow
-
         // Transition style for full page slide backgrounds
         backgroundTransition: {{ background_transition }}, // none/fade/slide/convex/concave/zoom
-
         // The maximum number of pages a single slide can expand onto when printing
         // to PDF, unlimited by default
         pdfMaxPagesPerSlide: {{ pdf_max_pages_per_slide }},
-
         // Prints each fragment on a separate slide
         pdfSeparateFragments: {{ pdf_separate_fragments }},
-
         // Offset used to reduce the height of content within exported PDF pages.
         // This exists to account for environment differences based on how you
         // print to PDF. CLI printing options, like phantomjs and wkpdf, can end
         // on precisely the total height of the document whereas in-browser
         // printing has to end one pixel before.
         pdfPageHeightOffset: {{ pdf_page_height_offset }},
-
         // Number of slides away from the current that are visible
         viewDistance: {{ view_distance }},
-
         // Number of slides away from the current that are visible on mobile
         // devices. It is advisable to set this to a lower number than
         // viewDistance in order to save resources.
         mobileViewDistance: {{ mobile_view_distance }},
-
         // The display mode that will be used to show slides
         display: {{ display }},
-
         // Hide cursor if inactive
         hideInactiveCursor: {{ hide_inactive_cursor }},
-
         // Time before the cursor is hidden (in ms)
         hideCursorTime: {{ hide_cursor_time }}
       });
-
-      {% if one_file -%}
+      // Override SPACE to play / pause the video
+      Reveal.addKeyBinding(
+        {
+          keyCode: 32,
+          key: 'SPACE',
+          description: 'Play / pause video'
+        },
+        () => {
+          var currentVideos = Reveal.getCurrentSlide().slideBackgroundContentElement.getElementsByTagName("video");
+          if (currentVideos.length > 0) {
+            if (currentVideos[0].paused == true) currentVideos[0].play();
+            else currentVideos[0].pause();
+          } else {
+            Reveal.next();
+          }
+        }
+      );
+      {% if one_file %}
       // Fix found by @t-fritsch and @Rapsssito on GitHub
       // see: https://github.com/hakimel/reveal.js/discussions/3362#discussioncomment-11733074.
       function setVideoBase64(video) {
@@ -362,15 +321,14 @@
       }
       // Setup base64 videos
       Reveal.on( 'ready', fixBase64VideoBackground );
-      {%- endif %}
+      {% endif %}
     </script>
-
-    {% if env['READTHEDOCS'] -%}
-    <style>
-      readthedocs-flyout, readthedocs-notification {
-        display: none;
-      }
-    </style>
-    {%- endif %}
+    {% if env['READTHEDOCS'] %}
+      <style>
+        readthedocs-flyout, readthedocs-notification {
+          display: none;
+        }
+      </style>
+    {% endif %}
   </body>
 </html>

manim_slides/cli/present/__init__.py

@@ -0,0 +1 @@
+"""Manim Slides' presentation commands."""

manim_slides/cli/present/commands.py

@@ -7,9 +7,14 @@ import click
 from click import Context, Parameter
 from pydantic import ValidationError
 
-from ..commons import config_path_option, folder_path_option, verbosity_option
-from ..config import Config, PresentationConfig
-from ..logger import logger
+from ...core.config import Config, PresentationConfig, list_presentation_configs
+from ...core.logger import logger
+from ..commons import (
+    config_path_option,
+    folder_path_option,
+    scenes_argument,
+    verbosity_option,
+)
 
 
 @click.command()
@@ -18,8 +23,10 @@ from ..logger import logger
 @verbosity_option
 def list_scenes(folder: Path) -> None:
     """List available scenes."""
-    for i, scene in enumerate(_list_scenes(folder), start=1):
-        click.secho(f"{i}: {scene}", fg="green")
+    scene_names = [path.stem for path in list_presentation_configs(folder)]
+    num_digits = len(str(len(scene_names)))
+    for i, scene_name in enumerate(scene_names, start=1):
+        click.secho(f"{i:{num_digits}d}: {scene_name}", fg="green")
 
 
 def _list_scenes(folder: Path) -> list[str]:
@@ -130,7 +137,7 @@ def start_at_callback(
 
 
 @click.command()
-@click.argument("scenes", nargs=-1)
+@scenes_argument
 @config_path_option
 @folder_path_option
 @click.option("--start-paused", is_flag=True, help="Start paused.")
@@ -276,7 +283,7 @@ def present(  # noqa: C901
     if skip_all:
         exit_after_last_slide = True
 
-    presentation_configs = get_scenes_presentation_config(scenes, folder)
+    presentation_configs = [PresentationConfig.from_file(path) for path in scenes]
 
     if config_path.exists():
         try:

manim_slides/cli/render/commands.py

@@ -1,14 +1,4 @@
-"""
-Alias command to either
-``manim render [OPTIONS] [ARGS]...`` or
-``manimgl -w [OPTIONS] [ARGS]...``.
-
-This is especially useful for two reasons:
-
-1. You can are sure to execute the rendering command with the same Python environment
-   as for ``manim-slides``.
-2. You can pass options to the config.
-"""
+"""Manim Slides' rendering commands."""
 
 import subprocess
 import sys
@@ -44,10 +34,22 @@ def render(ce: bool, gl: bool, args: tuple[str, ...]) -> None:
 
     Use ``manim-slides render --help`` to see help information for
     a specific renderer.
+
+    Alias command to either
+    ``manim render [OPTIONS] [ARGS]...`` or
+    ``manimgl [OPTIONS] [ARGS]...``.
+
+    This is especially useful for two reasons:
+
+    1. You can are sure to execute the rendering command with the same Python environment
+       as for ``manim-slides``.
+    2. You can pass options to the config.
     """
     if ce and gl:
         raise click.UsageError("You cannot specify both --CE and --GL renderers.")
     if gl:
         subprocess.run([sys.executable, "-m", "manimlib", "-w", *args])
     else:
-        subprocess.run([sys.executable, "-m", "manim", "render", *args])
+        from manim.cli.render.commands import render as render_ce
+
+        render_ce(args, standalone_mode=False)

manim_slides/cli/wizard/__init__.py

@@ -0,0 +1 @@
+"""Manim Slides' wizard."""

manim_slides/cli/wizard/commands.py

@@ -3,10 +3,9 @@ from pathlib import Path
 
 import click
 
+from ...core.config import Config
+from ...core.logger import logger
 from ..commons import config_options, verbosity_option
-from ..config import Config
-from ..defaults import CONFIG_PATH
-from ..logger import logger
 
 
 @click.command()
@@ -37,7 +36,7 @@ def _init(
     mode.
     """
     if config_path.exists():
-        click.secho(f"The `{CONFIG_PATH}` configuration file exists")
+        logger.debug(f"The `{config_path}` configuration file exists")
 
         if not force and not merge:
             choice = click.prompt(
@@ -57,7 +56,7 @@ def _init(
     if force:
         logger.debug(f"Overwriting `{config_path}` if exists")
     elif merge:
-        logger.debug("Merging new config into `{config_path}`")
+        logger.debug(f"Merging new config into `{config_path}`")
 
     if not skip_interactive:
         if config_path.exists():
@@ -82,4 +81,4 @@ def _init(
 
     config.to_file(config_path)
 
-    click.secho(f"Configuration file successfully saved to `{config_path}`")
+    logger.debug(f"Configuration file successfully saved to `{config_path}`")

manim_slides/core/config.py

@@ -1,3 +1,5 @@
+"""Manim Slides' configuration tools."""
+
 import json
 import shutil
 from functools import wraps
@@ -13,6 +15,7 @@ from pydantic import (
     FilePath,
     PositiveInt,
     PrivateAttr,
+    ValidationError,
     conset,
     field_serializer,
     field_validator,
@@ -26,28 +29,54 @@ Receiver = Callable[..., Any]
 
 
 class Signal(BaseModel):  # type: ignore[misc]
-    __receivers: list[Receiver] = PrivateAttr(default_factory=list)
+    """Signal that notifies a list of receivers when it is emitted."""
+
+    __receivers: set[Receiver] = PrivateAttr(default_factory=set)
 
     def connect(self, receiver: Receiver) -> None:
-        self.__receivers.append(receiver)
+        """
+        Connect a receiver to this signal.
+
+        This is a no-op if the receiver was already connected to this signal.
+
+        :param receiver: The receiver to connect.
+        """
+        self.__receivers.add(receiver)
 
     def disconnect(self, receiver: Receiver) -> None:
-        self.__receivers.remove(receiver)
+        """
+        Disconnect a receiver from this signal.
+
+        This is a no-op if the receiver was not connected to this signal.
+
+        :param receiver: The receiver to disconnect.
+        """
+        self.__receivers.discard(receiver)
 
     def emit(self, *args: Any) -> None:
+        """
+        Emit this signal and call each of the attached receivers.
+
+        :param args: Positional arguments passed to each receiver.
+        """
         for receiver in self.__receivers:
             receiver(*args)
 
 
 def key_id(name: str) -> PositiveInt:
-    """Avoid importing Qt too early."""
-    from qtpy.QtCore import Qt
+    """
+    Return the id corresponding to the given key name.
+
+    :param str: The name of the key, e.g., 'Q'.
+    :return: The corresponding id.
+    """
+    from qtpy.QtCore import Qt  # Avoid importing Qt too early."""
 
     return getattr(Qt, f"Key_{name}")
 
 
 class Key(BaseModel):  # type: ignore[misc]
-    """Represents a list of key codes, with optionally a name."""
+    """Represent a list of key codes, with optionally a name."""
 
     ids: conset(PositiveInt, min_length=1)  # type: ignore[valid-type]
     name: Optional[str] = None
@@ -58,6 +87,7 @@ class Key(BaseModel):  # type: ignore[misc]
         self.ids = set(ids)
 
     def match(self, key_id: int) -> bool:
+        """Return whether a given key id matches this key."""
         m = key_id in self.ids
 
         if m:
@@ -135,6 +165,7 @@ class Config(BaseModel):  # type: ignore[misc]
     """General Manim Slides config."""
 
     keys: Keys = Field(default_factory=Keys)
+    """The key mapping."""
 
     @classmethod
     def from_file(cls, path: Path) -> "Config":
@@ -142,11 +173,16 @@ class Config(BaseModel):  # type: ignore[misc]
         return cls.model_validate(rtoml.load(path))  # type: ignore
 
     def to_file(self, path: Path) -> None:
-        """Dump the configuration to a file."""
+        """Dump this configuration to a file."""
         rtoml.dump(self.model_dump(), path, pretty=True)
 
     def merge_with(self, other: "Config") -> "Config":
-        """Merge with another config."""
+        """
+        Merge with another config.
+
+        :param other: The other config to be merged with.
+        :return: This config, updated.
+        """
         self.keys = self.keys.merge_with(other.keys)
         return self
 
@@ -155,11 +191,19 @@ class BaseSlideConfig(BaseModel):  # type: ignore
     """Base class for slide config."""
 
     loop: bool = False
+    """Whether this slide should loop."""
     auto_next: bool = False
+    """Whether this slide is skipped upon completion."""
     playback_rate: float = 1.0
+    """The speed at which the animation is played (1.0 is normal)."""
     reversed_playback_rate: float = 1.0
+    """The speed at which the reversed animation is played."""
     notes: str = ""
+    """The notes attached to this slide."""
     dedent_notes: bool = True
+    """Whether to automatically remove any leading indentation in the notes."""
+    skip_animations: bool = False
+    src: Optional[FilePath] = None
 
     @classmethod
     def wrapper(cls, arg_name: str) -> Callable[..., Any]:
@@ -171,7 +215,11 @@ class BaseSlideConfig(BaseModel):  # type: ignore
         The wrapped function must follow two criteria:
         - its last parameter must be ``**kwargs`` (or equivalent);
         - and its second last parameter must be ``<arg_name>``.
+
+        :param arg_name: The name of the argument.
+        :return: The wrapped function.
         """
+        # TODO: improve docs and (maybe) type-hints too
 
         def _wrapper_(fun: Callable[..., Any]) -> Callable[..., Any]:
             @wraps(fun)
@@ -204,21 +252,27 @@ class BaseSlideConfig(BaseModel):  # type: ignore
         return _wrapper_
 
     @model_validator(mode="after")
-    @classmethod
     def apply_dedent_notes(
-        cls, base_slide_config: "BaseSlideConfig"
+        self,
     ) -> "BaseSlideConfig":
-        if base_slide_config.dedent_notes:
-            base_slide_config.notes = dedent(base_slide_config.notes)
+        """
+        Remove indentation from notes, if specified.
 
-        return base_slide_config
+        :return: The config, optionally modified.
+        """
+        if self.dedent_notes:
+            self.notes = dedent(self.notes)
+
+        return self
 
 
 class PreSlideConfig(BaseSlideConfig):
     """Slide config to be used prior to rendering."""
 
     start_animation: int
+    """The index of the first animation."""
     end_animation: int
+    """The index after the last animation."""
 
     @classmethod
     def from_base_slide_config_and_animation_indices(
@@ -227,6 +281,13 @@ class PreSlideConfig(BaseSlideConfig):
         start_animation: int,
         end_animation: int,
     ) -> "PreSlideConfig":
+        """
+        Create a config from a base config and animation indices.
+
+        :param base_slide_config: The base config.
+        :param start_animation: The index of the first animation.
+        :param end_animation: The index after the last animation.
+        """
         return cls(
             start_animation=start_animation,
             end_animation=end_animation,
@@ -236,30 +297,48 @@ class PreSlideConfig(BaseSlideConfig):
     @field_validator("start_animation", "end_animation")
     @classmethod
     def index_is_posint(cls, v: int) -> int:
+        """
+        Validate that animation indices are positive integers.
+
+        :param v: An animation index.
+        :return: The animation index, if valid.
+        """
         if v < 0:
             raise ValueError("Animation index (start or end) cannot be negative")
         return v
 
     @model_validator(mode="after")
-    @classmethod
     def start_animation_is_before_end(
-        cls, pre_slide_config: "PreSlideConfig"
+        self,
     ) -> "PreSlideConfig":
-        if pre_slide_config.start_animation >= pre_slide_config.end_animation:
-            if pre_slide_config.start_animation == pre_slide_config.end_animation == 0:
-                raise ValueError(
-                    "You have to play at least one animation (e.g., `self.wait()`) "
-                    "before pausing. If you want to start paused, use the appropriate "
-                    "command-line option when presenting. "
-                    "IMPORTANT: when using ManimGL, `self.wait()` is not considered "
-                    "to be an animation, so prefer to directly use `self.play(...)`."
-                )
+        """
+        Validate that start and end animation indices satisfy 'start < end'.
 
+        :return: The config, if indices are valid.
+        """
             raise ValueError(
                 "Start animation index must be strictly lower than end animation index"
             )
+        return self
 
-        return pre_slide_config
+    @model_validator(mode="after")
+    def has_src_or_more_than_zero_animations(
+        self,
+    ) -> "PreSlideConfig":
+        if self.src is not None and self.start_animation != self.end_animation:
+            raise ValueError(
+                "A slide cannot have 'src=...' and more than zero animations at the same time."
+            )
+        elif self.src is None and self.start_animation == self.end_animation:
+            raise ValueError(
+                "You have to play at least one animation (e.g., 'self.wait()') "
+                "before pausing. If you want to start paused, use the appropriate "
+                "command-line option when presenting. "
+                "IMPORTANT: when using ManimGL, 'self.wait()' is not considered "
+                "to be an animation, so prefer to directly use 'self.play(...)'."
+            )
+
+        return self
 
     @property
     def slides_slice(self) -> slice:
@@ -270,7 +349,9 @@ class SlideConfig(BaseSlideConfig):
     """Slide config to be used after rendering."""
 
     file: FilePath
+    """The file containing the animation."""
     rev_file: FilePath
+    """The file containing the reversed animation."""
 
     @classmethod
     def from_pre_slide_config_and_files(
@@ -280,13 +361,22 @@ class SlideConfig(BaseSlideConfig):
 
 
 class PresentationConfig(BaseModel):  # type: ignore[misc]
+    """Presentation config that contains all necessary information for a presentation."""
+
     slides: list[SlideConfig] = Field(min_length=1)
+    """The non-empty list of slide configs."""
     resolution: tuple[PositiveInt, PositiveInt] = (1920, 1080)
+    """The resolution of the animation files."""
     background_color: Color = "black"
+    """The background color of the animation files."""
 
     @classmethod
     def from_file(cls, path: Path) -> "PresentationConfig":
-        """Read a presentation configuration from a file."""
+        """
+        Read a presentation configuration from a file.
+
+        :param path: The path where the config is read from.
+        """
         with open(path) as f:
             obj = json.load(f)
 
@@ -303,7 +393,11 @@ class PresentationConfig(BaseModel):  # type: ignore[misc]
             return cls.model_validate(obj)  # type: ignore
 
     def to_file(self, path: Path) -> None:
-        """Dump the presentation configuration to a file."""
+        """
+        Dump the presentation configuration to a file.
+
+        :param path: The path to save this config.
+        """
         with open(path, "w") as f:
             f.write(self.model_dump_json(indent=2))
 
@@ -314,7 +408,14 @@ class PresentationConfig(BaseModel):  # type: ignore[misc]
         include_reversed: bool = True,
         prefix: str = "",
     ) -> None:
-        """Copy the files to a given directory."""
+        """
+        Copy the files to a given directory and return the corresponding configuration.
+
+        :param folder: The folder that will contain the animation files.
+        :param use_cached: Whether caching should be used to avoid copies when possible.
+        :param include_reversed: Whether to also copy reversed animation to the folder.
+        :param prefix: Optional prefix added to each file name.
+        """
         for slide_config in self.slides:
             file = slide_config.file
             rev_file = slide_config.rev_file
@@ -326,4 +427,6 @@ class PresentationConfig(BaseModel):  # type: ignore[misc]
                 shutil.copy(file, dest)
 
             if include_reversed and (not use_cached or not rev_dest.exists()):
+                # TODO: if include_reversed is False, then rev_dev will likely not exist
+                # and this will cause an issue when decoding.
                 shutil.copy(rev_file, rev_dest)

manim_slides/core/defaults.py

@@ -1,4 +1,8 @@
+"""Manim Slides' defaults."""
+
 from pathlib import Path
 
 FOLDER_PATH: Path = Path("./slides")
+"""Folder where slides are stored."""
 CONFIG_PATH: Path = Path(".manim-slides.toml")
+"""Path to local Manim Slides config."""

manim_slides/core/logger.py

@@ -31,7 +31,11 @@ HIGHLIGHTED_KEYWORDS = [  # these keywords are highlighted specially
 
 
 def make_logger() -> logging.Logger:
-    """Make a logger similar to the one used by Manim."""
+    """
+    Make a logger similar to the one used by Manim.
+
+    :return: The logger instance.
+    """
     RichHandler.KEYWORDS = HIGHLIGHTED_KEYWORDS
     rich_handler = RichHandler(
         show_time=True,
@@ -47,6 +51,5 @@ def make_logger() -> logging.Logger:
     return logger
 
 
-make_logger()
-
-logger = logging.getLogger("manim-slides")
+logger = make_logger()
+"""The logger instance used across this project."""

manim_slides/core/utils.py

@@ -1,16 +1,23 @@
 import hashlib
 import os
+import shutil
 import tempfile
 from collections.abc import Iterator
+from multiprocessing import Pool
 from pathlib import Path
+from typing import Any, Optional
 
 import av
+from tqdm import tqdm
 
 from .logger import logger
 
 
 def concatenate_video_files(files: list[Path], dest: Path) -> None:
     """Concatenate multiple video files into one."""
+    if len(files) == 1:
+        shutil.copy(files[0], dest)
+        return
 
     def _filter(files: list[Path]) -> Iterator[Path]:
         """Patch possibly empty video files."""
@@ -89,8 +96,9 @@ def link_nodes(*nodes: av.filter.context.FilterContext) -> None:
         c.link_to(n)
 
 
-def reverse_video_file(src: Path, dest: Path) -> None:
+def reverse_video_file_in_one_chunk(src_and_dest: tuple[Path, Path]) -> None:
     """Reverses a video file, writing the result to `dest`."""
+    src, dest = src_and_dest
     with (
         av.open(str(src)) as input_container,
         av.open(str(dest), mode="w") as output_container,
@@ -120,8 +128,70 @@ def reverse_video_file(src: Path, dest: Path) -> None:
 
         for _ in range(frames_count):
             frame = graph.pull()
-            frame.pict_type = 5  # Otherwise we get a warning saying it is changed
+            frame.pict_type = "NONE"  # Otherwise we get a warning saying it is changed
             output_container.mux(output_stream.encode(frame))
 
         for packet in output_stream.encode():
             output_container.mux(packet)
+
+
+def reverse_video_file(
+    src: Path,
+    dest: Path,
+    max_segment_duration: Optional[float] = 4.0,
+    num_processes: Optional[int] = None,
+    **tqdm_kwargs: Any,
+) -> None:
+    """Reverses a video file, writing the result to `dest`."""
+    with av.open(str(src)) as input_container:  # Fast path if file is short enough
+        input_stream = input_container.streams.video[0]
+        if max_segment_duration is None:
+            return reverse_video_file_in_one_chunk((src, dest))
+        elif input_stream.duration:
+            if (
+                float(input_stream.duration * input_stream.time_base)
+                <= max_segment_duration
+            ):
+                return reverse_video_file_in_one_chunk((src, dest))
+        else:  # pragma: no cover
+            logger.debug(
+                f"Could not determine duration of {src}, falling back to segmentation."
+            )
+
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            tmpdir = Path(tmpdirname)
+            with av.open(
+                str(tmpdir / f"%04d.{src.suffix}"),
+                "w",
+                format="segment",
+                options={"segment_time": str(max_segment_duration)},
+            ) as output_container:
+                output_stream = output_container.add_stream(
+                    template=input_stream,
+                )
+
+                for packet in input_container.demux(input_stream):
+                    if packet.dts is None:
+                        continue
+
+                    packet.stream = output_stream
+                    output_container.mux(packet)
+
+            src_files = list(tmpdir.iterdir())
+            rev_files = [
+                src_file.with_stem("rev_" + src_file.stem) for src_file in src_files
+            ]
+
+            with Pool(num_processes, maxtasksperchild=1) as pool:
+                for _ in tqdm(
+                    pool.imap_unordered(
+                        reverse_video_file_in_one_chunk, zip(src_files, rev_files)
+                    ),
+                    desc="Reversing large file by cutting it in segments",
+                    total=len(src_files),
+                    unit=" files",
+                    **tqdm_kwargs,
+                ):
+                    pass  # We just consume the iterator
+
+            concatenate_video_files(rev_files[::-1], dest)

manim_slides/ipython/ipython_magic.py

@@ -116,7 +116,7 @@ class ManimSlidesMagic(Magics):  # type: ignore
             file) will be moved relative to the video locations. Use-cases include building
             documentation with Sphinx and JupyterBook. See also the
             :mod:`Manim Slides directive for Sphinx
-            <manim_slides.docs.manim_slides_directive>`.
+            <manim_slides.sphinxext.manim_slides_directive>`.
 
         Examples
         --------

manim_slides/slide/__init__.py

@@ -1,10 +1,12 @@
-__all__ = [
+"""Slides module with logic to either import ManimCE or ManimGL."""
+
+__all__ = (
     "API_NAME",
     "MANIM",
     "MANIMGL",
     "Slide",
     "ThreeDSlide",
-]
+)
 
 
 import os
@@ -14,10 +16,10 @@ import sys
 class ManimApiNotFoundError(ImportError):
     """Error raised if specified manim API could be imported."""
 
-    _msg = "Could not import the specified manim API"
+    _msg = "Could not import the specified manim API: `{api}`."
 
-    def __init__(self) -> None:
-        super().__init__(self._msg)
+    def __init__(self, api: str) -> None:
+        super().__init__(self._msg.format(api=api))
 
 
 API_NAMES = {
@@ -26,9 +28,12 @@ API_NAMES = {
     "manimlib": "manimlib",
     "manimgl": "manimlib",
 }
+"""Allowed values for API."""
 
 MANIM_API: str = "MANIM_API"
+"""API environ variable name."""
 FORCE_MANIM_API: str = "FORCE_" + MANIM_API
+"""FORCE API environ variable name."""
 
 API: str = os.environ.get(MANIM_API, "manim").lower()
 
@@ -53,11 +58,14 @@ if MANIM:
     try:
         from .manim import Slide, ThreeDSlide
     except ImportError as e:
-        raise ManimApiNotFoundError from e
+        raise ManimApiNotFoundError("manim") from e
 elif MANIMGL:
     try:
         from .manimlib import Slide, ThreeDSlide
     except ImportError as e:
-        raise ManimApiNotFoundError from e
+        raise ManimApiNotFoundError("manimlib") from e
 else:
-    raise ManimApiNotFoundError
+    raise ValueError(
+        "This error should never occur. "
+        "Please report an issue on GitHub if you encounter it."
+    )

manim_slides/slide/base.py

@@ -1,6 +1,8 @@
+"""Base class for the Slide class."""
+
 from __future__ import annotations
 
-__all__ = ["BaseSlide"]
+__all__ = ("BaseSlide",)
 
 import platform
 import shutil
@@ -15,10 +17,15 @@ from typing import (
 import numpy as np
 from tqdm import tqdm
 
-from ..config import BaseSlideConfig, PresentationConfig, PreSlideConfig, SlideConfig
-from ..defaults import FOLDER_PATH
-from ..logger import logger
-from ..utils import concatenate_video_files, merge_basenames, reverse_video_file
+from ..core.config import (
+    BaseSlideConfig,
+    PresentationConfig,
+    PreSlideConfig,
+    SlideConfig,
+)
+from ..core.defaults import FOLDER_PATH
+from ..core.logger import logger
+from ..core.utils import concatenate_video_files, merge_basenames, reverse_video_file
 from . import MANIM
 
 if TYPE_CHECKING:
@@ -36,6 +43,8 @@ class BaseSlide:
     disable_caching: bool = False
     flush_cache: bool = False
     skip_reversing: bool = False
+    max_duration_before_split_reverse: float | None = 4.0
+    num_processes: int | None = None
 
     def __init__(
         self, *args: Any, output_folder: Path = FOLDER_PATH, **kwargs: Any
@@ -49,6 +58,7 @@ class BaseSlide:
         self._start_animation = 0
         self._canvas: MutableMapping[str, Mobject] = {}
         self._wait_time_between_slides = 0.0
+        self._skip_animations = False
 
     @property
     @abstractmethod
@@ -277,7 +287,7 @@ class BaseSlide:
         self._wait_time_between_slides = max(wait_time, 0.0)
 
     def play(self, *args: Any, **kwargs: Any) -> None:
-        """Overload `self.play` and increment animation count."""
+        """Overload 'self.play' and increment animation count."""
         super().play(*args, **kwargs)  # type: ignore[misc]
         self._current_animation += 1
 
@@ -299,6 +309,16 @@ class BaseSlide:
             Positional arguments passed to
             :meth:`Scene.next_section<manim.scene.scene.Scene.next_section>`,
             or ignored if `manimlib` API is used.
+        :param skip_animations:
+            Exclude the next slide from the output.
+
+            If `manim` is used, this is also passed to :meth:`Scene.next_section<manim.scene.scene.Scene.next_section>`,
+            which will avoid rendering the corresponding animations.
+
+            .. seealso::
+
+                :meth:`start_skip_animations`
+                :meth:`stop_skip_animations`
         :param loop:
             If set, next slide will be looping.
         :param auto_next:
@@ -335,6 +355,11 @@ class BaseSlide:
                 ``manim-slides convert --to=pptx``.
         :param dedent_notes:
             If set, apply :func:`textwrap.dedent` to notes.
+        :param pathlib.Path src:
+            An optional path to a video file to include as next slide.
+
+            The video will be copied into the output folder, but no rescaling
+            is applied.
         :param kwargs:
             Keyword arguments passed to
             :meth:`Scene.next_section<manim.scene.scene.Scene.next_section>`,
@@ -458,6 +483,21 @@ class BaseSlide:
 
             self._current_slide += 1
 
+        if base_slide_config.src is not None:
+            self._slides.append(
+                PreSlideConfig.from_base_slide_config_and_animation_indices(
+                    base_slide_config,
+                    self._current_animation,
+                    self._current_animation,
+                )
+            )
+
+            base_slide_config = BaseSlideConfig()  # default
+            self._current_slide += 1
+
+        if self._skip_animations:
+            base_slide_config.skip_animations = True
+
         self._base_slide_config = base_slide_config
         self._start_animation = self._current_animation
 
@@ -477,7 +517,7 @@ class BaseSlide:
             )
         )
 
-    def _save_slides(
+    def _save_slides(  # noqa: C901
         self,
         use_cache: bool = True,
         flush_cache: bool = False,
@@ -516,14 +556,25 @@ class BaseSlide:
 
         for pre_slide_config in tqdm(
             self._slides,
-            desc=f"Concatenating animation files to '{scene_files_folder}' and generating reversed animations",
+            desc=f"Concatenating animations to '{scene_files_folder}' and generating reversed animations",
             leave=self._leave_progress_bar,
             ascii=True if platform.system() == "Windows" else None,
             disable=not self._show_progress_bar,
+            unit=" slides",
         ):
-            slide_files = files[pre_slide_config.slides_slice]
+            if pre_slide_config.skip_animations:
+                continue
+            if pre_slide_config.src:
+                slide_files = [pre_slide_config.src]
+            else:
+                slide_files = files[pre_slide_config.slides_slice]
 
-            file = merge_basenames(slide_files)
+            try:
+                file = merge_basenames(slide_files)
+            except ValueError as e:
+                raise ValueError(
+                    f"Failed to merge basenames of files for slide: {pre_slide_config!r}"
+                ) from e
             dst_file = scene_files_folder / file.name
             rev_file = scene_files_folder / f"{file.stem}_reversed{file.suffix}"
 
@@ -536,7 +587,15 @@ class BaseSlide:
                 if skip_reversing:
                     rev_file = dst_file
                 else:
-                    reverse_video_file(dst_file, rev_file)
+                    reverse_video_file(
+                        dst_file,
+                        rev_file,
+                        max_segment_duration=self.max_duration_before_split_reverse,
+                        num_processes=self.num_processes,
+                        leave=self._leave_progress_bar,
+                        ascii=True if platform.system() == "Windows" else None,
+                        disable=not self._show_progress_bar,
+                    )
 
             slides.append(
                 SlideConfig.from_pre_slide_config_and_files(
@@ -560,6 +619,22 @@ class BaseSlide:
             f"Slide '{scene_name}' configuration written in '{slide_path.absolute()}'"
         )
 
+    def start_skip_animations(self) -> None:
+        """
+        Start skipping animations.
+
+        This automatically applies ``skip_animations=True``
+        to all subsequent calls to :meth:`next_slide`.
+
+        This is useful when you want to skip animations from multiple slides in a row,
+        without having to manually set ``skip_animations=True``.
+        """
+        self._skip_animations = True
+
+    def stop_skip_animations(self) -> None:
+        """Stop skipping animations."""
+        self._skip_animations = False
+
     def wipe(
         self,
         *args: Any,

manim_slides/slide/manim.py

@@ -1,3 +1,5 @@
+"""Manim's implementation of the Slide class."""
+
 from pathlib import Path
 from typing import Any, Optional
 
@@ -5,32 +7,49 @@ from manim import Scene, ThreeDScene, config
 from manim.renderer.opengl_renderer import OpenGLRenderer
 from manim.utils.color import rgba_to_color
 
-from ..config import BaseSlideConfig
+from ..core.config import BaseSlideConfig
 from .base import BaseSlide
 
 
 class Slide(BaseSlide, Scene):  # type: ignore[misc]
     """
-    Inherits from :class:`Scene<manim.scene.scene.Scene>` and provide necessary tools
+    Inherits from :class:`Scene<manim.scene.scene.Scene>` and provides 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 pathlib.Path 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.
+    :cvar typing.Optional[float] max_duration_before_split_reverse: :data:`4.0`: Maximum duration
+        before of a video animation before it is reversed by splitting the file into smaller chunks.
+        Generating reversed animations can require an important amount of
+        memory (because the whole video needs to be kept in memory),
+        and splitting the video into multiple chunks usually speeds
+        up the process (because it can be done in parallel) while taking
+        less memory.
+        Set this to :data:`None` to disable splitting the file into chunks.
+    :cvar typing.Optional[int] num_processes: :data:`None`: Number of processes
+        to use for parallelizable operations.
+        If :data:`None`, defaults to :func:`os.process_cpu_count`.
+        This is currently used when generating reversed animations, and can
+        increase memory consumption.
     """
 
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # OpenGL renderer disables 'write_to_movie' by default
+        # which is required for saving the animations
+        config["write_to_movie"] = True
+        super().__init__(*args, **kwargs)
+
     @property
     def _frame_shape(self) -> tuple[float, float]:
         if isinstance(self.renderer, OpenGLRenderer):
@@ -89,6 +108,15 @@ class Slide(BaseSlide, Scene):  # type: ignore[misc]
     def _start_at_animation_number(self) -> Optional[int]:
         return config["from_animation_number"]  # type: ignore
 
+    def play(self, *args: Any, **kwargs: Any) -> None:
+        """Overload 'self.play' and increment animation count."""
+        super().play(*args, **kwargs)
+
+        if self._base_slide_config.skip_animations:
+            # Manim will not render the animations, so we reset the animation
+            # counter to the previous value
+            self._current_animation -= 1
+
     def next_section(self, *args: Any, **kwargs: Any) -> None:
         """
         Alias to :meth:`next_slide`.
@@ -111,7 +139,12 @@ class Slide(BaseSlide, Scene):  # type: ignore[misc]
         base_slide_config: BaseSlideConfig,
         **kwargs: Any,
     ) -> None:
-        Scene.next_section(self, *args, **kwargs)
+        Scene.next_section(
+            self,
+            *args,
+            skip_animations=base_slide_config.skip_animations | self._skip_animations,
+            **kwargs,
+        )
         BaseSlide.next_slide.__wrapped__(
             self,
             base_slide_config=base_slide_config,

manim_slides/slide/manimlib.py

@@ -1,3 +1,5 @@
+"""ManimGL's implementation of the Slide class."""
+
 from pathlib import Path
 from typing import Any, ClassVar, Optional
 

manim_slides/sphinxext/manim_slides_directive.py

@@ -40,7 +40,7 @@ First, you must include the directive in the Sphinx configuration file:
 
     extensions = [
         # ...
-        "manim_slides.docs.manim_slides_directive",
+        "manim_slides.sphinxext.manim_slides_directive",
     ]
 
 Its basic usage that allows processing **inline content**

pyproject.toml

@@ -2,6 +2,39 @@
 build-backend = "hatchling.build"
 requires = ["hatchling", "hatch-fancy-pypi-readme"]
 
+[dependency-groups]
+dev = [
+  {include-group = "docs"},
+  {include-group = "tests"},
+  "bump-my-version>=0.20.3",
+  "pre-commit>=3.5.0",
+]
+docs = [
+  "manim-slides[magic,manim,pyqt6,sphinx-directive]",
+  "furo>=2023.5.20",
+  "ipykernel>=6.25.1",
+  "myst-parser>=2.0.0",
+  "nbsphinx>=0.9.2",
+  "pandoc>=2.3",
+  "pygments<2.19",  # See: https://github.com/ManimCommunity/manim/issues/4104
+  "sphinx>=7.0.1",
+  "sphinxcontrib-programoutput>=0.18",
+  "sphinx-design>=0.6.1",
+  "sphinx-click>=4.4.0",
+  "sphinx-copybutton>=0.5.1",
+  "sphinxext-opengraph>=0.7.5",
+]
+tests = [
+  "importlib-metadata>=8.6.1;python_version<'3.10'",
+  "manim-slides[full,manimgl,pyqt6,pyside6,sphinx-directive]",
+  "pytest>=7.4.0",
+  "pytest-cov>=4.1.0",
+  "pytest-env>=0.8.2",
+  "pytest-missing-modules>=0.1.0",
+  "pytest-qt>=4.2.0",
+  "setuptools>=73.0.1",
+]
+
 [project]
 authors = [{name = "Jérome Eertmans", email = "jeertmans@icloud.com"}]
 classifiers = [
@@ -42,43 +75,20 @@ name = "manim-slides"
 requires-python = ">=3.9"
 
 [project.optional-dependencies]
-docs = [
-  "manim-slides[magic,manim,pyqt6,sphinx-directive]",
-  "furo>=2023.5.20",
-  "ipykernel>=6.25.1",
-  "myst-parser>=2.0.0",
-  "nbsphinx>=0.9.2",
-  "pandoc>=2.3",
-  "pygments<2.19",  # See: https://github.com/ManimCommunity/manim/issues/4104
-  "sphinx>=7.0.1",
-  "sphinxcontrib-programoutput>=0.18",
-  "sphinx-design>=0.6.1",
-  "sphinx-click>=4.4.0",
-  "sphinx-copybutton>=0.5.1",
-  "sphinxext-opengraph>=0.7.5",
-]
 full = [
   "manim-slides[magic,manim,sphinx-directive]",
 ]
 magic = ["manim-slides[manim]", "ipython>=8.12.2"]
-manim = ["manim>=0.17"]
+manim = ["manim>=0.19"]
 manimgl = ["manimgl>=1.7.2"]
 pyqt6 = ["pyqt6>=6.7.0"]
 pyqt6-full = ["manim-slides[full,pyqt6]"]
 pyside6 = ["pyside6>=6.6.1,!=6.8.1.1"]
 pyside6-full = ["manim-slides[full,pyside6]"]
 sphinx-directive = ["docutils>=0.20.1", "manim-slides[manim]"]
-tests = [
-  "manim-slides[full,manimgl,pyqt6,pyside6,sphinx-directive]",
-  "pytest>=7.4.0",
-  "pytest-cov>=4.1.0",
-  "pytest-env>=0.8.2",
-  "pytest-missing-modules>=0.1.0",
-  "pytest-qt>=4.2.0",
-]
 
 [project.scripts]
-manim-slides = "manim_slides.__main__:cli"
+manim-slides = "manim_slides.cli.commands:main"
 
 [project.urls]
 Changelog = "https://github.com/jeertmans/manim-slides/releases"
@@ -91,7 +101,7 @@ Repository = "https://github.com/jeertmans/manim-slides"
 allow_dirty = false
 commit = true
 commit_args = ""
-current_version = "5.3.1"
+current_version = "5.5.1"
 ignore_missing_version = false
 message = "chore(deps): bump version from {current_version} to {new_version}"
 parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(-rc(?P<release>\d+))?'
@@ -137,13 +147,6 @@ replace = '''<!-- start changelog -->
 ## [Unreleased](https://github.com/jeertmans/manim-slides/compare/v{new_version}...HEAD)'''
 search = "<!-- start changelog -->"
 
-[[tool.bumpversion.files]]
-filename = "uv.lock"
-replace = '''name = "manim-slides"
-version = "{new_version}"'''
-search = '''name = "manim-slides"
-version = "{current_version}"'''
-
 [tool.codespell]
 builtin = "clear,rare,informal,usage,names,en-GB_to_en-US"
 check-hidden = true
@@ -205,10 +208,9 @@ filterwarnings = [
 ]
 
 [tool.ruff]
-extend-exclude = ["manim_slides/resources.py"]
+extend-exclude = ["manim_slides/cli/resources.py"]
 extend-include = ["*.ipynb"]
 line-length = 88
-target-version = "py39"
 
 [tool.ruff.lint]
 extend-ignore = [
@@ -231,10 +233,3 @@ isort = {known-first-party = ["manim_slides", "tests"]}
 [tool.ruff.lint.per-file-ignores]
 "docs/source/reference/magic_example.ipynb" = ["F403", "F405"]
 "tests/test_slide.py" = ["N801"]
-
-[tool.uv]
-dev-dependencies = [
-  "bump-my-version>=0.20.3",
-  "pre-commit>=3.5.0",
-  "setuptools>=73.0.1",
-]

tests/test_base_slide.py

@@ -86,6 +86,15 @@ class TestBaseSlide:
 
         assert base_slide.wait_time_between_slides == 0.0
 
+    def test_skip_animations(self, base_slide: BaseSlide) -> None:
+        assert not base_slide._skip_animations
+
+    def test_start_and_stop_skip_animations(self, base_slide: BaseSlide) -> None:
+        base_slide.start_skip_animations()
+        assert base_slide._skip_animations
+        base_slide.stop_skip_animations()
+        assert not base_slide._skip_animations
+
     def test_play(self) -> None:
         pass  # This method should be tested in test_slide.py
 

tests/test_slide.py

@@ -1,6 +1,10 @@
+import contextlib
+import os
 import random
 import shutil
 import sys
+import tempfile
+from collections.abc import Iterator
 from pathlib import Path
 from typing import Any, Union
 
@@ -17,6 +21,7 @@ from manim import (
     Dot,
     FadeIn,
     GrowFromCenter,
+    Square,
     Text,
 )
 from manim.renderer.opengl_renderer import OpenGLRenderer
@@ -65,7 +70,9 @@ Slide = Union[CESlide, _GLSlide, CEGLSlide]
                 reason="See https://github.com/3b1b/manim/issues/2263.",
             ),
         ),
+        "--CE --renderer=opengl",
     ],
+    ids=("CE", "GL", "CE(GL)"),
 )
 def test_render_basic_slide(
     renderer: str,
@@ -78,7 +85,7 @@ def test_render_basic_slide(
     with runner.isolated_filesystem() as tmp_dir:
         shutil.copy(manimgl_config, tmp_dir)
         results = runner.invoke(
-            render, [renderer, str(slides_file), "BasicSlide", "-ql"]
+            render, [*renderer.split(" "), str(slides_file), "BasicSlide", "-ql"]
         )
 
         assert results.exit_code == 0, results
@@ -229,8 +236,22 @@ def assert_constructs(cls: SlideType) -> None:
     init_slide(cls).construct()
 
 
+@contextlib.contextmanager
+def tmp_cwd() -> Iterator[str]:
+    cwd = os.getcwd()
+    tmp_dir = tempfile.mkdtemp()
+
+    os.chdir(tmp_dir)
+
+    try:
+        yield tmp_dir
+    finally:
+        os.chdir(cwd)
+
+
 def assert_renders(cls: SlideType) -> None:
-    init_slide(cls).render()
+    with tmp_cwd():
+        init_slide(cls).render()
 
 
 class TestSlide:
@@ -293,6 +314,26 @@ class TestSlide:
                 self.play(dot.animate.move_to(LEFT))
                 self.play(dot.animate.move_to(DOWN))
 
+    def test_split_reverse(self) -> None:
+        @assert_renders
+        class _(CESlide):
+            max_duration_before_split_reverse = 3.0
+
+            def construct(self) -> None:
+                self.wait(2.0)
+                for _ in range(3):
+                    self.next_slide()
+                    self.wait(10.0)
+
+        @assert_renders
+        class __(CESlide):
+            max_duration_before_split_reverse = None
+
+            def construct(self) -> None:
+                self.wait(5.0)
+                self.next_slide()
+                self.wait(5.0)
+
     def test_file_too_long(self) -> None:
         @assert_renders
         class _(CESlide):
@@ -479,6 +520,120 @@ class TestSlide:
                 self.next_slide()
                 assert self._current_slide == 2
 
+    def test_next_slide_skip_animations(self) -> None:
+        class Foo(CESlide):
+            def construct(self) -> None:
+                circle = Circle(color=BLUE)
+                self.play(GrowFromCenter(circle))
+                assert not self._base_slide_config.skip_animations
+                self.next_slide(skip_animations=True)
+                square = Square(color=BLUE)
+                self.play(GrowFromCenter(square))
+                assert self._base_slide_config.skip_animations
+                self.next_slide()
+                assert not self._base_slide_config.skip_animations
+                self.play(GrowFromCenter(square))
+
+        class Bar(CESlide):
+            def construct(self) -> None:
+                circle = Circle(color=BLUE)
+                self.play(GrowFromCenter(circle))
+                assert not self._base_slide_config.skip_animations
+                self.next_slide(skip_animations=False)
+                square = Square(color=BLUE)
+                self.play(GrowFromCenter(square))
+                assert not self._base_slide_config.skip_animations
+                self.next_slide()
+                assert not self._base_slide_config.skip_animations
+                self.play(GrowFromCenter(square))
+
+        class Baz(CESlide):
+            def construct(self) -> None:
+                circle = Circle(color=BLUE)
+                self.play(GrowFromCenter(circle))
+                assert not self._base_slide_config.skip_animations
+                self.start_skip_animations()
+                self.next_slide()
+                square = Square(color=BLUE)
+                self.play(GrowFromCenter(square))
+                assert self._base_slide_config.skip_animations
+                self.next_slide()
+                assert self._base_slide_config.skip_animations
+                self.play(GrowFromCenter(square))
+                self.stop_skip_animations()
+
+        with tmp_cwd() as tmp_dir:
+            init_slide(Foo).render()
+            init_slide(Bar).render()
+            init_slide(Baz).render()
+
+            slides_folder = Path(tmp_dir) / "slides"
+
+            assert slides_folder.exists()
+
+            slide_file = slides_folder / "Foo.json"
+
+            config = PresentationConfig.from_file(slide_file)
+
+            assert len(config.slides) == 2
+
+            slide_file = slides_folder / "Bar.json"
+
+            config = PresentationConfig.from_file(slide_file)
+
+            assert len(config.slides) == 3
+
+            slide_file = slides_folder / "Baz.json"
+
+            config = PresentationConfig.from_file(slide_file)
+
+            assert len(config.slides) == 1
+
+    def test_next_slide_include_video(self) -> None:
+        class Foo(CESlide):
+            def construct(self) -> None:
+                circle = Circle(color=BLUE)
+                self.play(GrowFromCenter(circle))
+                self.next_slide()
+                square = Square(color=BLUE)
+                self.play(GrowFromCenter(square))
+                self.next_slide()
+                self.wait(2)
+
+        with tmp_cwd() as tmp_dir:
+            init_slide(Foo).render()
+
+            slides_folder = Path(tmp_dir) / "slides"
+
+            assert slides_folder.exists()
+
+            slide_file = slides_folder / "Foo.json"
+
+            config = PresentationConfig.from_file(slide_file)
+
+            assert len(config.slides) == 3
+
+            class Bar(CESlide):
+                def construct(self) -> None:
+                    self.next_slide(src=config.slides[0].file)
+                    self.wait(2)
+                    self.next_slide()
+                    self.wait(2)
+                    self.next_slide()  # Dummy
+                    self.next_slide(src=config.slides[1].file, loop=True)
+                    self.next_slide()  # Dummy
+                    self.wait(2)
+                    self.next_slide(src=config.slides[2].file)
+
+            init_slide(Bar).render()
+
+            slide_file = slides_folder / "Bar.json"
+
+            config = PresentationConfig.from_file(slide_file)
+
+            assert len(config.slides) == 6
+            assert config.slides[-3].loop
+
     def test_canvas(self) -> None:
         @assert_constructs
         class _(CESlide):