mirror of
https://github.com/jeertmans/manim-slides.git
synced 2025-08-23 12:33:38 +08:00
04bca458f1
* chore(ci): checking links and spell checking * chore(ci): move markdown-link-check to GitHub ci Because pre-commit.ci does not have access to the internet... * fix(lib): revert `reverse-...` utils because of warnings * chore(ci): checking links and spell checking * chore(ci): move markdown-link-check to GitHub ci Because pre-commit.ci does not have access to the internet... * fix(docs): myst-parser xref cannot end with .html * fix(docs): oops
132 lines
3.4 KiB
Markdown
132 lines
3.4 KiB
Markdown
# Workflow
|
|
|
|
This document is there to help you recreate a working environment for Manim Slides.
|
|
|
|
## Dependencies
|
|
|
|
```{include} ../installation.md
|
|
: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](https://docs.github.com/en/get-started/quickstart/hello-world).
|
|
* [GitHub Pull Request in 100 Seconds](https://www.youtube.com/watch?v=8lGpZkjnkt4&ab_channel=Fireship).
|
|
|
|
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 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 PDM, installation becomes straightforward:
|
|
|
|
```bash
|
|
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 `-G|--group` option:
|
|
|
|
```bash
|
|
pdm install -Gmanim # For Manim
|
|
# or
|
|
pdm install -Gmanimgl # For ManimGL
|
|
```
|
|
|
|
Additionally, Manim Slides comes with groups of dependencies for development purposes:
|
|
|
|
```bash
|
|
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.:
|
|
|
|
```bash
|
|
pdm run manim-slides wizard
|
|
```
|
|
|
|
or [enter a new shell](https://pdm-project.org/latest/usage/venv/#activate-a-virtualenv)
|
|
that uses this new Python environment:
|
|
|
|
```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:
|
|
|
|
```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!
|
|
|
|
Many thanks to you!
|