manim-slides/docs/source/contributing/workflow.md

Workflow

This document is there to help you recreate a working environment for Manim Slides.

Dependencies

:start-after: <!-- start deps -->
:end-before: <!-- end deps -->

Forking the repository and cloning it locally

We use GitHub to host Manim Slides' repository, and we encourage contributors to use git.

Useful links:

• GitHub's Hello World.
• GitHub Pull Request in 100 Seconds.

Once you feel comfortable with git and GitHub, fork the repository, and clone it locally.

As for every Python project, using virtual environment is recommended to avoid conflicts between modules. For this project, we use PDM to easily manage project and development dependencies. If not already, please install this tool.

Installing Python modules

With PDM, installation becomes straightforward:

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, you can use the -G|--group option:

pdm install -Gmanim   # For Manim
# or
pdm install -Gmanimgl # For ManimGL

Additionnally, Manim Slides comes with groups of dependencies for development purposes:

pdm install -Gdev  # For linters and formatters
# or
pdm install -Gdocs # To build the documentation locally
# or
pdm install -Gtest # To run tests

:::{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

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.:

pdm run manim-slides wizard

or enter a new shell that uses this new Python environment:

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:

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:

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:

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 and wait for a reviewer to check your work!

Many thanks to you!