chore(deps): use PDM instead of Poetry (#354)

* chore(deps): use PDM instead of Poetry

* chore(git): move to top

* chore(lint): fixes

* fix(pdm): dynamic version did not work

* chore(ci): fix syntax for Windows

* fix(ci): typo

* wip(docs): updates

* chore(docs): add changelog entry

* chore(docs): admonitions

* chore(docs): update to use manim-slides render

* chore(docs): make it better

docs/source/conf.py

@@ -5,6 +5,9 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import sys
+from datetime import date
+
+from manim_slides import __version__
 
 assert sys.version_info >= (3, 10), "Building docs requires Python 3.10"
 
@@ -12,8 +15,9 @@ assert sys.version_info >= (3, 10), "Building docs requires Python 3.10"
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Manim Slides"
-copyright = "2023, Jérome Eertmans"
+copyright = f"2024-{date.today().year}, Jérome Eertmans"
 author = "Jérome Eertmans"
+version = __version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/contributing/workflow.md

@@ -4,7 +4,7 @@ This document is there to help you recreate a working environment for Manim Slid
 
 ## Dependencies
 
-```{include} ../../../README.md
+```{include} ../quickstart.md
 :start-after: <!-- start deps -->
 :end-before: <!-- end deps -->
 ```
@@ -20,64 +20,110 @@ Useful links:
 
 Once you feel comfortable with git and GitHub, [fork](https://github.com/jeertmans/manim-slides/fork) the repository, and clone it locally.
 
-As for every Python project, using virtual environment is recommended to avoid conflicts between modules. For Manim Slides, we use [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer). If not already, please install it.
+As for every Python project, using virtual environment is recommended to avoid
+conflicts between modules.
+For this project, we use [PDM](https://pdm-project.org/) to easily manage project
+and development dependencies. If not already, please install this tool.
 
 ## Installing Python modules
 
-With Poetry, installation becomes straightforward:
+With PDM, installation becomes straightforward:
 
 ```bash
-poetry install
+pdm 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:
+If you would like to install Manim or ManimGL,
+as documented in the [quickstart](../quickstart),
+you can use the `-G|--group` option:
 
 ```bash
-poetry install --extras manim   # For Manim
+pdm install -Gmanim   # For Manim
 # or
-poetry install --extras manimgl # For ManimGL
+pdm install -Gmanimgl # For ManimGL
 ```
 
-Additionnally, Manim Slides comes with group dependencies for development purposes:
+Additionnally, Manim Slides comes with groups of dependencies for development purposes:
 
 ```bash
-poetry install --with dev  # For linters and formatters
+pdm install -dGdev  # For linters and formatters
 # or
-poetry install --with docs # To build the documentation locally
+pdm install --dGdocs # To build the documentation locally
+# or
+pdm install --dGtests # To run tests
 ```
 
-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.
+
+You can also install everything with `pdm install -G:all`.
 :::
 
 ## Running commands
 
-As modules were installed in a new Python environment, you cannot use them directly in the shell.
-Instead, you either need to prepend `poetry run` to any command, e.g.:
+Because modules are installed in a new Python environment,
+you cannot use them directly in the shell.
+Instead, you either need to prepend `pdm run` to any command, e.g.:
 
 ```bash
-poetry run manim-slides wizard
+pdm run manim-slides wizard
 ```
 
-or enter a new shell that uses this new Python environment:
+or [enter a new shell](https://pdm-project.org/latest/usage/venv/#activate-a-virtualenv)
+that uses this new Python environment:
 
-```
-poetry shell
+```bash
+eval $(pdm venv activate)  # Click on the link above to see shell-specific command
 manim-slides wizard
 ```
 
 ## Testing your code
 
-Most of the tests are done with GitHub actions, thus not on your computer. The only command you should run locally is `pre-commit run --all-files`: this runs a few linter and formatter to make sure the code quality and style stay constant across time. If a warning or an error is displayed, please fix it before going to next step.
+Most of the tests are done with GitHub actions, thus not on your computer.
+The only command you should run locally is:
+
+```bash
+pdm run pre-commit run --all-files
+```
+
+This runs a few linter and formatter to make sure the code quality and style stay
+constant across time.
+If a warning or an error is displayed, please fix it before going to next step.
+
+For testing your code, simply run:
+
+```bash
+pdm run pytest
+```
+
+## Building the documentation
+
+The documentation is generated using Sphinx, based on the content
+in `docs/source` and in the `manim_slides` Python package.
+
+To generate the documentation, run the following:
+
+```bash
+cd docs
+pdm run make html
+```
+
+Then, the output index file is located at `docs/build/html/index.html` and
+can be opened with any modern browser.
+
+:::{warning}
+Building the documentation can take quite some time, especially
+the first time as it needs to render all the animations.
+
+Further builds should run faster.
+:::
 
 ## Proposing changes
 
-Once you feel ready and think your contribution is ready to be reviewed, create a [pull request](https://github.com/jeertmans/manim-slides/pulls) and wait for a reviewer to check your work!
+Once you feel ready and think your contribution is ready to be reviewed,
+create a [pull request](https://github.com/jeertmans/manim-slides/pulls)
+and wait for a reviewer to check your work!
 
 Many thanks to you!

docs/source/index.md

@@ -26,7 +26,6 @@ Manim Slides makes creating slides with Manim super easy!
 In a [very few steps](./quickstart),
 you can create slides and present them either using the GUI, or your browser.
 
-
 Slide through the demo below to get a quick glimpse on what you can do with
 Manim Slides.
 
@@ -40,6 +39,7 @@ Manim Slides.
 :hidden:
 
 quickstart
+installation
 reference/index
 features_table
 manim_or_manimgl

docs/source/installation.md

@@ -0,0 +1,104 @@
+# Installation
+
+While installing Manim Slides and its dependencies on your global Python is fine,
+we recommend using a virtual environment
+(e.g., [venv](https://docs.python.org/3/tutorial/venv.html)) for a local installation.
+
+Therefore, the following documentation will install Manim Slides using
+[pipx](https://pipx.pypa.io/). This tool is a drop-in replacement
+for installing Python packages that ship with one or more executable.
+
+The benefit of using pipx is that it will automatically create a new virtual
+environment for every package you install.
+
+:::{note}
+Everytime you read `pipx install`, you can use `pip install` instead,
+if you are working in a virtual environment or else.
+:::
+
+## Dependencies
+
+Manim Slides requires either Manim or ManimGL to be installed, along
+with their dependencies.
+Having both packages installed is fine too.
+
+If none of those packages are installed,
+please refer to their specific installation guidelines:
+- [Manim](https://docs.manim.community/en/stable/installation.html)
+- [ManimGL](https://3b1b.github.io/manim/getting_started/installation.html)
+
+:::{warning}
+If you install Manim from its git repository, as suggested by ManimGL,
+make sure to first check out a supported version (e.g., `git checkout tags/v1.6.1`
+for ManimGL), otherwise it might install an unsupported version of Manim!
+See [#314](https://github.com/jeertmans/manim-slides/issues/314).
+:::
+
+## Pip Install
+
+The recommended way to install the latest release is to use pip:
+
+```bash
+pipx install -U manim-slides
+```
+
+:::{tip}
+While not necessary, the `-U` indicates that we would
+like to upgrade to the latest version available,
+if Manim Slides is already installed.
+:::
+
+Optionally, you can also install Manim or ManimGL using extras[^1]:
+
+```bash
+pipx install -U "manim-slides[manim]"   # For Manim
+# or
+pipx install -U "manim-slides[manimgl]" # For ManimGL
+```
+
+You can check that Manim Slides was correctly installed with:
+
+```bash
+manim-slides --version
+```
+
+:::{warning}
+If you are installing with pipx, this is mandatory to at least include
+either `manim` or `manimgl`.
+:::
+
+[^1]: You still need to have Manim or ManimGL platform-specific dependencies
+  installed on your computer.
+
+## Optional Dependencies
+
+Along with the optional dependencies for Manim and ManimGL,
+Manim Slides offers additional *extras*, that can be activated
+using optional dependencies:
+
+- `magic`, to include a Jupyter magic to render
+  animations inside notebooks. This automatically installs `manim`,
+  and does not work with ManimGL;
+- `manim` and `manimgl`, for installing the corresponding
+  dependencies;
+- `sphinx-directive`, to generate presentation inside your Sphinx
+  documentation. This automatically installs `manim`,
+  and does not work with ManimGL;
+
+Installing those extras can be done with the following syntax:
+
+```bash
+pipx install -U "manim-slides[extra1,extra2]"
+```
+
+:::{note}
+The quotes `"` are added because not all shell support unquoted
+brackets (e.g., zsh) or commas (e.g., Windows).
+:::
+
+## Install From Repository
+
+An alternative way to install Manim Slides is to clone the git repository,
+and install from there: read the
+[contributing guide](./contributing/workflow)
+to know how to process.

docs/source/quickstart.md

@@ -1,11 +1,7 @@
 # Quickstart
 
-## Installation
-
-```{include} ../../README.md
-:start-after: <!-- start install -->
-:end-before: <!-- end install -->
-```
+If not already, install Manim Slides, along with either Manim or ManimGL,
+see [installation](./installation).
 
 ## Creating your first slides
 

docs/source/reference/sharing.md

@@ -9,8 +9,10 @@ We will go from the *most restrictive* method, to the least restrictive one.
 If you need to present on a computer without prior knowledge on what will be
 installed on it, please directly refer to the last sections.
 
-> **NOTES:** in the next sections, we will assume your animations are described
+:::{note}
+In the next sections, we will assume your animations are described
 in `example.py`, and you have one presentation called `BasicExample`.
+:::
 
 ## With Manim Slides installed on the target machine
 
@@ -32,8 +34,8 @@ the key bindings might not be the same.
 Example:
 
 ```bash
-# If you use ManimGl, replace `manim` with `manimgl`
-manim example.py BasicExample
+# If you use ManimGl, add `--GL` after `render`
+manim-slides render example.py BasicExample
 
 # This or `manim-slides BasicExample` works since
 # `present` is implied by default
@@ -128,7 +130,6 @@ The additional code comes from
 [this article](https://faq.dailymotion.com/hc/en-us/articles/360022841393-How-to-preserve-the-player-aspect-ratio-on-a-responsive-page)
 and it there to preserve the original aspect ratio (16:9).
 
-
 ### Sharing ONE HTML file
 
 If you set the `data_uri` option to `true` (with `-cdata_uri=true`),
@@ -144,10 +145,11 @@ This is how your are able to watch all the examples on this website. If you want
 to know how to share your slide with GitHub pages, see the
 [workflow file](https://github.com/jeertmans/manim-slides/blob/main/.github/workflows/pages.yml).
 
-> **WARNING:** keep in mind that playing large video files over the internet
+:::{warning}
+Keep in mind that playing large video files over the internet network
 can take some time, and *glitches* may occur between slide transitions for this
 reason.
-
+:::
 
 ### Using the Github starter template