Merge branch 'main' into gui-scenes

updates:
- [github.com/charliermarsh/ruff-pre-commit: v0.0.263 → v0.0.265](https://github.com/charliermarsh/ruff-pre-commit/compare/v0.0.263...v0.0.265)

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

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 4.12.0
+current_version = 4.13.1
 commit = True
 message = chore(version): bump {current_version} to {new_version}
 

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+- package-ecosystem: github-actions
+  directory: /
+  schedule:
+    interval: daily
+  labels:
+  - dependencies

.github/workflows/pages.yml

@@ -46,22 +46,24 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install libcairo2-dev libpango1.0-dev ffmpeg freeglut3-dev
-    - name: Install Python dependencies
-      run: pip install manim sphinx sphinx_click furo
     - name: Install local Python package
-      run: poetry install --with docs
+      run: poetry install --extras=manim --with docs
     - name: Restore cached media
       id: cache-media-restore
       uses: actions/cache/restore@v3
       with:
         path: media
         key: ${{ runner.os }}-media
-    - name: Build animation and convert it into HTML slides
+    - name: Build animations
       run: |
         poetry run manim example.py ConvertExample BasicExample ThreeDExample
-        poetry run manim-slides convert ConvertExample docs/source/_static/slides.html -ccontrols=true
-        poetry run manim-slides convert BasicExample docs/source/_static/basic_example.html -ccontrols=true
-        poetry run manim-slides convert ThreeDExample docs/source/_static/three_d_example.html -ccontrols=true
+    - name: Convert animations to HTML slides
+      run: |
+        poetry run manim-slides convert -v DEBUG ConvertExample docs/source/_static/slides.html -ccontrols=true
+        poetry run manim-slides convert -v DEBUG BasicExample docs/source/_static/basic_example.html -ccontrols=true
+        poetry run manim-slides convert -v DEBUG ThreeDExample docs/source/_static/three_d_example.html -ccontrols=true
+    - name: Show docs/source/_static/ dir content (video only)
+      run: tree -L 3 docs/source/_static/ -P '*.mp4'
     - name: Clear cache
       run: |
         gh extension install actions/gh-actions-cache
@@ -82,6 +84,8 @@ jobs:
       with:
         # Upload docs/build/html dir
         path: docs/build/html/
+    - name: Show docs/build/html/_static/ dir content (video only)
+      run: tree -L 3 docs/build/html/_static/ -P '*.mp4'
     - name: Deploy to GitHub Pages
       id: deployment
       if: github.event_name != 'pull_request'

.github/workflows/python-publish.yml

@@ -1,4 +1,3 @@
-# Modified from: https://github.com/pypa/cibuildwheel
 name: Upload Python Package
 
 on:
@@ -8,41 +7,28 @@ on:
     types: [published]
 
 jobs:
-  build_wheels:
-    name: Build wheels on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
+  build_and_release:
+    name: Build and release
+    runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - name: Checkout repository
+      uses: actions/checkout@v3
 
-    - uses: actions/setup-python@v2
+    - name: Install Poetry
+      run: pipx install poetry
 
-    - name: Install build package
-      run: python -m pip install -U build
+    - name: Install Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+        cache: poetry
 
     - name: Build wheels
-      run: python -m build --sdist
+      run: poetry build
 
-    - uses: actions/upload-artifact@v2
-      with:
-        name: dist
-        path: dist/*.tar.*
-
-  release:
-    name: Release
+    - name: Publish to PyPI
       if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-    runs-on: ubuntu-latest
-    needs: [build_wheels]
-    steps:
-    - uses: actions/download-artifact@v2
-      with:
-        name: dist
-        path: dist/
-    - name: Upload to PyPI
-      uses: pypa/gh-action-pypi-publish@master
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_API_TOKEN }}
+      env:
+        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_API_TOKEN }}
+      run: poetry publish

.github/workflows/test_examples.yml

@@ -1,6 +1,8 @@
 on:
   pull_request:
     paths:
+    - pyproject.toml
+    - poetry.lock
     - '**.py'
     - .github/workflows/test_examples.yml
   workflow_dispatch:

.pre-commit-config.yaml

@@ -24,11 +24,11 @@ repos:
   hooks:
   - id: black
 - repo: https://github.com/charliermarsh/ruff-pre-commit
-  rev: v0.0.260
+  rev: v0.0.265
   hooks:
   - id: ruff
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.1.1
+  rev: v1.2.0
   hooks:
   - id: mypy
     additional_dependencies: [types-requests, types-setuptools]

README.md

@@ -27,6 +27,9 @@ Tool for live presentations using either [Manim (community edition)](https://www
 - [F.A.Q](#faq)
   * [How to increase quality on Windows](#how-to-increase-quality-on-windows)
 - [Contributing](#contributing)
+  * [Reporting an Issue](#reporting-an-issue)
+  * [Seeking for Help](#seeking-for-help)
+  * [Contact](#contact)
 
 ## Installation
 
@@ -54,6 +57,16 @@ The recommended way to install the latest release is to use pip:
 pip install manim-slides
 ```
 
+Optionally, you can also install Manim or ManimGL using extras[^1]:
+
+```bash
+pip install manim-slides[manim]   # For Manim
+# or
+pip install manim-slides[manimgl] # For ManimGL
+```
+
+[^1]: NOTE: you still need to have Manim or ManimGL platform-specific dependencies installed on your computer.
+
 ### Install From Repository
 
 An alternative way to install Manim Slides is to clone the git repository, and install from there: read the [contributing guide](https://eertmans.be/manim-slides/contributing/workflow.html) to know how.
@@ -190,6 +203,55 @@ in *Settings*->*Display*.
 
 Contributions are more than welcome! Please read through [our contributing section](https://eertmans.be/manim-slides/contributing/index.html).
 
+### Reporting an Issue
+
+<!-- start reporting-an-issue -->
+
+If you think you found a bug,
+an error in the documentation,
+or wish there was some feature that is currently missing,
+we would love to hear from you!
+
+The best way to reach us is via the
+[GitHub issues](https://github.com/jeertmans/manim-slides/issues).
+If your problem is not covered by an already existing (closed or open) issue,
+then we suggest you create a
+[new issue](https://github.com/jeertmans/manim-slides/issues/new/choose).
+You can choose from a list of templates, or open a
+[blank issue](https://github.com/jeertmans/manim-slides/issues/new)
+if your issue does not fit one of the proposed topics.
+
+The more precise you are in the description of your problem, the faster we will
+be able to help you!
+
+<!-- end reporting-an-issue -->
+
+### Seeking for help
+
+<!-- start seeking-for-help -->
+
+Sometimes, you may have a question about Manim Slides,
+not necessarily an issue.
+
+There are two ways you can reach us for questions:
+
+- via the `Question/Help/Support` topic when
+[choosing an issue template](https://github.com/jeertmans/manim-slides/issues/new/choose);
+- or via
+[GitHub discussions](https://github.com/jeertmans/manim-slides/discussions).
+
+<!-- end seeking-for-help -->
+
+### Contact
+
+<!-- start contact -->
+
+Finally, if you do not have any GitHub account,
+or just wish to contact the author of Manim Slides,
+you can do so at: [jeertmans@icloud.com](mailto:jeertmans@icloud.com).
+
+<!-- end contact -->
+
 [pypi-version-badge]: https://img.shields.io/pypi/v/manim-slides?label=manim-slides
 [pypi-version-url]: https://pypi.org/project/manim-slides/
 [pypi-python-version-badge]: https://img.shields.io/pypi/pyversions/manim-slides

docs/source/contributing/index.md

@@ -2,10 +2,14 @@
 
 Thank you for your interest in Manim Slides! ✨
 
-Manim Slides is an open source project, first created as a fork of [manim-presentation](https://github.com/galatolofederico/manim-presentation) (now deprecated in favor to Manim Slides), and we welcome contributions of all forms.
-
-This section is here to help fist-time contributors know how they can help this project grow. Whether you are already familiar with Manim or GitHub, it is worth taking a few minutes to read those documents!
+Manim Slides is an open source project, first created as a fork of
+[manim-presentation](https://github.com/galatolofederico/manim-presentation)
+(now deprecated in favor to Manim Slides),
+and we welcome contributions of all forms.
 
+This section is here to help fist-time contributors know how they can help this
+project grow. Whether you are already familiar with Manim or GitHub,
+it is worth taking a few minutes to read those documents!
 
 ```{toctree}
 :hidden:
@@ -19,3 +23,24 @@ internals
 
 [Internals](./internals)
 : how Manim Slides is built and how the various parts of it work.
+
+## Reporting an Issue
+
+```{include} ../../../README.md
+:start-after: <!-- start reporting-an-issue -->
+:end-before: <!-- end reporting-an-issue -->
+```
+
+## Seeking for Help
+
+```{include} ../../../README.md
+:start-after: <!-- start seeking-for-help -->
+:end-before: <!-- end seeking-for-help -->
+```
+
+## Contact
+
+```{include} ../../../README.md
+:start-after: <!-- start contact -->
+:end-before: <!-- end contact -->
+```

docs/source/contributing/workflow.md

@@ -11,7 +11,7 @@ This document is there to help you recreate a working environment for Manim Slid
 
 ## Forking the repository and cloning it locally
 
-We used GitHub to host Manim Slides' repository, and we encourage contributors to use git.
+We use GitHub to host Manim Slides' repository, and we encourage contributors to use git.
 
 Useful links:
 
@@ -30,6 +30,32 @@ With Poetry, installation becomes straightforward:
 poetry install
 ```
 
+This, however, only installs the minimal set of dependencies to run the package.
+
+If you would like to install Manim or ManimGL, as documented in the [quickstart](../quickstart),
+you can use the `--extras` option:
+
+```bash
+poetry install --extras manim   # For Manim
+# or
+poetry install --extras manimgl # For ManimGL
+```
+
+Additionnally, Manim Slides comes with group dependencies for development purposes:
+
+```bash
+poetry install --with dev  # For linters and formatters
+# or
+poetry install --with docs # To build the documentation locally
+```
+
+Another group is `test`, but it is only used for
+[GitHub actions](https://github.com/jeertmans/manim-slides/blob/main/.github/workflows/test_examples.yml).
+
+:::{note}
+You can combine any number of groups or extras when installing the package locally.
+:::
+
 ## Running commands
 
 As modules were installed in a new Python environment, you cannot use them directly in the shell.

docs/source/reference/api.md

@@ -1,6 +1,6 @@
 # Application Programming Interface
 
-Manim Slides' API is very limited: it simply consists in two classes, `Slide` and `ThreeDSlide`, which are subclasses of `Scene` and `ThreeDScene` from Manim.
+Manim Slides' API is very limited: it simply consists of two classes, `Slide` and `ThreeDSlide`, which are subclasses of `Scene` and `ThreeDScene` from Manim.
 
 Thefore, we only document here the methods we think the end-user will ever use, not the methods used internally when rendering.
 

docs/source/reference/html.md

@@ -4,7 +4,7 @@ Manim Slides allows you to convert presentations into one HTML file, with
 [RevealJS](https://revealjs.com/). This file can then be opened with any modern
 web browser, allowing for a nice portability of your presentations.
 
-As for every command with Manim Slides, converting slides' fragments into one
+As with every command with Manim Slides, converting slides' fragments into one
 HTML file (and its assets) can be done in one command:
 
 ```bash

docs/source/reference/sharing.md

@@ -67,7 +67,7 @@ and the corresponding tree:
 ## Without Manim Slides installed on the target machine
 
 An alternative to `manim-slides present` is `manim-slides convert`.
-Currently, only HTML conversion is available, but do not hesitate to propose
+Currently, HTML and PPTX conversion are available, but do not hesitate to propose
 other formats by creating a
 [Feature Request](https://github.com/jeertmans/manim-slides/issues/new/choose),
 or directly proposing a

manim_slides/__version__.py

@@ -1 +1 @@
-__version__ = "4.12.0"
+__version__ = "4.13.1"

manim_slides/commons.py

@@ -54,7 +54,7 @@ def verbosity_option(function: F) -> F:
         "-v",
         "--verbosity",
         type=click.Choice(
-            ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+            ["PERF", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
             case_sensitive=False,
         ),
         help="Verbosity of CLI output",

manim_slides/convert.py

@@ -54,7 +54,7 @@ def validate_config_option(
 class Converter(BaseModel):  # type: ignore
     presentation_configs: List[PresentationConfig] = []
     assets_dir: str = "{basename}_assets"
-    template: Optional[str] = None
+    template: Optional[Path] = None
 
     def convert_to(self, dest: Path) -> None:
         """Converts self, i.e., a list of presentations, into a given format."""
@@ -314,6 +314,8 @@ class RevealJS(Converter):
                 file = presentation_config.files[slide_config.start_animation]
                 file = assets_dir / file.name
 
+                logger.debug(f"Writing video section with file {file}")
+
                 # TODO: document this
                 # Videos are muted because, otherwise, the first slide never plays correctly.
                 # This is due to a restriction in playing audio without the user doing anything.
@@ -327,9 +329,8 @@ class RevealJS(Converter):
 
     def load_template(self) -> str:
         """Returns the RevealJS HTML template as a string."""
-        if isinstance(self.template, str):
-            with open(self.template, "r") as f:
-                return f.read()
+        if isinstance(self.template, Path):
+            return self.template.read_text()
 
         if sys.version_info < (3, 9):
             return resources.read_text(data, "revealjs_template.html")
@@ -350,6 +351,8 @@ class RevealJS(Converter):
         )
         full_assets_dir = dirname / assets_dir
 
+        logger.debug(f"Assets will be saved to: {full_assets_dir}")
+
         os.makedirs(full_assets_dir, exist_ok=True)
 
         for presentation_config in self.presentation_configs:

manim_slides/logger.py

@@ -5,7 +5,9 @@ https://github.com/ManimCommunity/manim/blob/d5b65b844b8ce8ff5151a2f56f9dc98cebb
 
 import logging
 
+from rich.console import Console
 from rich.logging import RichHandler
+from rich.theme import Theme
 
 __all__ = ["logger", "make_logger"]
 
@@ -33,9 +35,12 @@ def make_logger() -> logging.Logger:
     RichHandler.KEYWORDS = HIGHLIGHTED_KEYWORDS
     rich_handler = RichHandler(
         show_time=True,
+        console=Console(theme=Theme({"logging.level.perf": "magenta"})),
     )
+    logging.addLevelName(5, "PERF")
     logger = logging.getLogger("manim-slides")
     logger.addHandler(rich_handler)
+
     return logger
 
 

manim_slides/present.py

@@ -14,7 +14,7 @@ from pydantic import ValidationError
 from pydantic.color import Color
 from PySide6.QtCore import Qt, QThread, Signal, Slot
 from PySide6.QtGui import QCloseEvent, QIcon, QImage, QKeyEvent, QPixmap, QResizeEvent
-from PySide6.QtWidgets import QApplication, QGridLayout, QLabel, QWidget
+from PySide6.QtWidgets import QApplication, QFileDialog, QGridLayout, QLabel, QWidget
 from tqdm import tqdm
 
 from .commons import config_path_option, verbosity_option
@@ -448,6 +448,21 @@ class Display(QThread):  # type: ignore
 
             lag = now() - last_time
             sleep_time = 1 / self.current_presentation.fps
+
+            logger.log(
+                5,
+                f"Took {lag:.3f} seconds to process the current frame, that must play at a rate of one every {sleep_time:.3f} seconds.",
+            )
+
+            if sleep_time - lag < 0:
+                logger.warn(
+                    "The FPS rate could not be matched. "
+                    "This is normal when manually transitioning between slides.\n"
+                    "If you feel that the FPS are too low, "
+                    "consider checking this issue:\n"
+                    "https://github.com/jeertmans/manim-slides/issues/179."
+                )
+
             sleep_time = max(sleep_time - lag, 0)
             time.sleep(sleep_time)
             last_time = now()
@@ -1012,6 +1027,22 @@ def present(
     Use `manim-slide list-scenes` to list all available scenes in a given folder.
     """
 
+    app = QApplication(sys.argv)
+    app.setApplicationName("Manim Slides")
+    dialog = QFileDialog()
+    dialog.setDirectory(FOLDER_PATH if os.path.exists(FOLDER_PATH) else "")
+    dialog.setFileMode(QFileDialog.ExistingFiles)
+    dialog.setNameFilters(["JSON (*.json)", "* (*.*)"])
+    if dialog.exec():
+        filenames = dialog.selectedFiles()
+        print(filenames)
+
+    # TODO:
+    # - get files in selected order
+    # - kill dialog
+    # - add cli option (+ envvar) to prompt gui instead of cli
+    # - use scenes selected from gui
+
     if skip_all:
         exit_after_last_slide = True
 

paper/paper.md

@@ -64,13 +64,16 @@ provide new features on a regular basis.
 
 # Easy to Use Commitment
 
-Manim Slides is commited to be an easy-to-use tool, when minimal installation
+Manim Slides is commited to be an easy-to-use tool, with minimal installation
 procedure and few modifications required. It can either be used locally with its
-graphical user interface (GUI), or shared via HTML thanks to the RevealJS
-Javascript package [@revealjs].
+graphical user interface (GUI), or shared via one of the two formats it can
+convert to:
+
+* an HTML page thanks to the RevealJS Javascript package [@revealjs];
+* or a PowerPoint (`.pptx`) file.
 
 This work has a very similar syntax to Manim and offers a comprehensive
-documentation hosted on [GitHub pages](https://eertmans.be/manim-slides/), see
+documentation hosted on [GitHub pages](https://jeertmans.github.io/manim-slides/), see
 \autoref{fig:docs}.
 
 ![Manim Slides' documentation homepage.\label{fig:docs}](docs.png)
@@ -79,10 +82,10 @@ documentation hosted on [GitHub pages](https://eertmans.be/manim-slides/), see
 
 We have used manim-presentation for our presentation at the COST
 Interact, hosted in Lyon, 2022, and
-[available online](https://eertmans.be/research/cost-interact-presentation/).
+[available online](https://web.archive.org/web/20230507184944/https://eertmans.be/posts/cost-interact-presentation/).
 This experience highly motivated the development of Manim Slides, and our
 EuCAP 2023 presentation slides are already
-[available online](https://eertmans.be/research/eucap-presentation/), thanks
+[available online](https://web.archive.org/web/20230507211243/https://eertmans.be/posts/eucap-presentation/), thanks
 to Manim Slides' HTML feature.
 
 Also, one of our users created a short
@@ -92,8 +95,8 @@ and posted it on YouTube.
 # Stability and releases
 
 Manim Slides is continously tested on most recent Python versions, both ManimCE
-and ManimGL, and on all major platforms: **Ubuntu**, **macOS** and **Windows**. As of Manim
-Slide's exposed API begin very minimal, and the variaty of tests that are
+and ManimGL, and on all major platforms: **Ubuntu**, **macOS** and **Windows**. Due to Manim
+Slide's exposed API being very minimal, and the variety of tests that are
 performed, this tool can be considered stable over time.
 
 New releases are very frequent, as they mostly introduce enhancements or small
@@ -111,12 +114,31 @@ presenting Manim content in front of an audience much easier than before,
 allowing presenters to focus more on the content of their slides, rather than on
 how to actually present them efficiently.
 
+## Target Audience
+
+Manim Slides was developed with the goal of making educational content more
+accessible than ever. We believe that researchers, professors, teaching
+assistants and anyone else who needs to teach scientific content can benefit
+from using this tool. The ability to pace your presentation yourself is
+essential, and Manim Slides gives you that ability.
+
+## A Need for Portability
+
+One of the major concerns with presenting content in a non-standard format
+(i.e., not just a plain PDF) is the issue of portability.
+Depending on the programs available, the power of the target computer,
+or the access to the internet, not all solutions are equal.
+From the same configuration file, Manim Slides offers a series of solutions to
+share your slides, which we discuss on our
+[Sharing your slides](https://jeertmans.github.io/manim-slides/reference/sharing.html)
+page.
+
 # Acknowledgements
 
 We acknowledge the work of [@manim-presentation] that paved the initial structure
 of Manim Slides with the manim-presentation Python package.
 
-We also acknowledge Grant Sanderson for its termendous work on Manim, as well as
+We also acknowledge Grant Sanderson for his tremendous work on Manim, as
 well as the Manim Community contributors.
 
 Finally, we also acknowledge contributions from the GitHub contributors on the

pyproject.toml

@@ -43,12 +43,14 @@ packages = [
 ]
 readme = "README.md"
 repository = "https://github.com/jeertmans/manim-slides"
-version = "4.12.0"
+version = "4.13.1"
 
 [tool.poetry.dependencies]
 click = "^8.1.3"
 click-default-group = "^1.2.2"
 lxml = "^4.9.2"
+manim = {version = "^0.17.0", optional = true}
+manimgl = {version = "^1.6.1", optional = true}
 numpy = "^1.19"
 opencv-python = "^4.6.0.66"
 pydantic = "^1.10.2"
@@ -59,6 +61,10 @@ requests = "^2.28.1"
 rich = "^13.3.2"
 tqdm = "^4.64.1"
 
+[tool.poetry.extras]
+manim = ["manim"]
+manimgl = ["manimgl"]
+
 [tool.poetry.group.dev.dependencies]
 black = "^22.10.0"
 bump2version = "^1.0.1"