diff --git a/.github/workflows/deploy-website.yaml b/.github/workflows/deploy-website.yaml index 6490ddc..5d60531 100644 --- a/.github/workflows/deploy-website.yaml +++ b/.github/workflows/deploy-website.yaml @@ -16,7 +16,7 @@ jobs: - name: Setup Python uses: actions/setup-python@v5 with: - python-version: "3.11" + python-version: "3.12" - name: Install and Build run: | diff --git a/.github/workflows/test-build.yaml b/.github/workflows/test-build.yaml index 46f7efc..c2b7112 100644 --- a/.github/workflows/test-build.yaml +++ b/.github/workflows/test-build.yaml @@ -12,10 +12,10 @@ jobs: - name: Setup python uses: actions/setup-python@v5 with: - python-version: "3.11" + python-version: "3.12" - name: Install and build run: | bash setup.sh - python3.11 -m build + python3 -m build make html diff --git a/library/design/sketch.py b/library/design/sketch.py index 4af59ae..39a09cc 100644 --- a/library/design/sketch.py +++ b/library/design/sketch.py @@ -3,8 +3,7 @@ from __future__ import annotations -from typing import Callable, Self, Any -from typing_extensions import override +from typing import Callable, Self, Any, override from abc import ABC, abstractmethod import enum diff --git a/requirements.txt b/requirements.txt index 213c24b..17690b2 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,7 +6,6 @@ myst-parser>=1.0.0 # animation libraries manim>=0.18 -typing-extensions>=4.5.0 setuptools numpy>=1.24.2 diff --git a/style.md b/style.md index a2dd816..d2fc411 100644 --- a/style.md +++ b/style.md @@ -1,28 +1,36 @@ # Style + This document describes the style guide for the website and animations. # Animations + ## Timing + Avoid running animations with non-standard units of time. Prefer using one of the following values: `0, 0.25, 0.5, 0.75, 1, 1.5, 2, 2.5, 3, 4, 5...` When setting the pace of an animation, consider that animations may play in a format which is not easily -pausable, and that many users prefer a slower format. +pausable, and that many users prefer a slower format. Animations should always finish with a delay equal to `style.animation.END_DELAY`. ## Colors + Use the `Color` type and colors defined in `style`. Do not use colors from manim directly. ## Building Animations + Animations used on the live website should be built as `gif`s with medium (`-qm`) quality. The output file name (`-o [FILENAME]`) should be lowercase with underscores for spaces. + ``` %%manim -v CRITICAL --format gif --disable_caching -qm -o boundary_constraints BoundaryConstraintScene ``` ## Using Animations -Animations should generally be displayed using the `figure` environment. + +Animations should generally be displayed using the `figure` environment. Animations should be displayed in the website by copying them from `animations` into the appropriate folder in `source`. + ``` :::{figure} boundary_constraints.gif :alt: Constraining the boundary @@ -31,69 +39,86 @@ Animations should be displayed in the website by copying them from `animations` Constraining a boundary line ::: ``` + Tutorials must place all rendered video content in a folder named `video`. # Code + ## Writing Animations -Animation helpers and members should be marked with `_`. + +Animation helpers and members should be marked with `_`. `setup` should be used to set constant data for scenes. Large animations may choose to abbreviate `self` as `s`. Scenes should not be passed as arguments to classes without good reason. ## Classes + ### Naming -Class members should generally be marked private by prepending an underscore, e.g. `_my_value`. + +Class members should generally be marked private by prepending an underscore, e.g. `_my_value`. Internal class methods should also be marked private by prepending an underscore, e.g. `_internal_func`. Setters should be prepended with `set`. Note setters should be made chainable by having them return an instace of themselves. -Getters may be prepended with `get`, but this is optional. Prefer writing a `getter` over making a +Getters may be prepended with `get`, but this is optional. Prefer writing a `getter` over making a value `public`. ### Chaining + Setters, as well as other methods with no default return value, should generally enable chaining by returning an instance of themselves (Typed using `Self`). ### Factories -Classes with factory methods should include the methods as static members and name them `make`. + +Classes with factory methods should include the methods as static members and name them `make`. Do not require calling setter methods between initialization of a class and use of a class method. -For non-trivial classes, prefer to use direct injection and write factories instead of writing +For non-trivial classes, prefer to use direct injection and write factories instead of writing complex constructors. ## Imports + Avoid polluting namespaces by importing with `*`. Manim may be imported using `from Manim import *`. Import user types using `from rc_lib import math_types as T`. Import other custom types directly. ## Types + Classes should be typed using Python type hints. The following rules apply: -* Type the return type of `__init__` methods with `None`. -* Use defined types from `math_types` and elsewhere as appropriate. Avoid using `np.ndarray` directly. -* User defined types may be imported aliased as `T`. -* Union types should be defined using Python 10 `|` syntax, e.g. `str | None` instead of `Optional[str]`. -* Note `Optional` is used for kwargs which are intended to allow explicitly passing the value `None`. This should not be confused - with not passing the type at all. -* Use `Self` when a method returns an instance of it's own class. -* Type returns using the base class. For example, return an `Animation`, not a `Succession`, and a `VMObject`, not a `VGroup`. + +- Type the return type of `__init__` methods with `None`. +- Use defined types from `math_types` and elsewhere as appropriate. Avoid using `np.ndarray` directly. +- User defined types may be imported aliased as `T`. +- Union types should be defined using Python 10 `|` syntax, e.g. `str | None` instead of `Optional[str]`. +- Note `Optional` is used for kwargs which are intended to allow explicitly passing the value `None`. This should not be confused + with not passing the type at all. +- Use `Self` when a method returns an instance of it's own class. +- Type returns using the base class. For example, return an `Animation`, not a `Succession`, and a `VMObject`, not a `VGroup`. ## Spelling + Spellings not recognized by the spellchecker should either corrected or added to the `.vscode` workspace settings using the quick fix menu. # Website + ## Headers + Headers should be written in capital case, e.g. **My Header** instead of **My header**. ## Hyperlinks + Avoid displaying hyperlinks directly in the website; use aliases instead. ## Directives -Use colons (`:::`) instead of backticks (`` ``` ``) to mark directives. + +Use colons (`:::`) instead of backticks (` ``` `) to mark directives. ## Admonition Directives + Admonitions are directives which may be used to create special info boxes which -define additional information. +define additional information. + ``` :::{note} Consider doing X. @@ -105,41 +130,45 @@ Do Y first to prevent X. ``` Admonitions should be used somewhat sparingly in order to avoid oversaturating users. -Admonition content should be written in complete sentences with proper punctuation. +Admonition content should be written in complete sentences with proper punctuation. `warning` and `danger` admonitions should also generally include a description of the consequence if the information is disregarded. Below is a detailed breakdown of the different types of admonitions as well as guidance on when to use them: + - `note`: Use `note` to define information which is possibly relevant but not directly related to the task at hand. \ - Example: "You should commit your changes consistently when working on code." + Example: "You should commit your changes consistently when working on code." - `warning`: Use `warning` to define information that, when missed, may cause confusion or additional problems. \ - Example: "Make sure you have chocolatey installed first; otherwise, the install may fail." + Example: "Make sure you have chocolatey installed first; otherwise, the install may fail." - `danger`: Use `danger` to define information that, when missed, may cause serious problems which are challenging to fix. \ - Example: "Make sure you have chocolatey installed first; otherwise, the install may become corrupted." + Example: "Make sure you have chocolatey installed first; otherwise, the install may become corrupted." - `important`: Use `important` to define information which is highly relevant but which does not have any significant consequences if missed. Note there is some grey area between `important` and `warning`; use your best judgement. \ - Example: "If you use `--amend` to modify a commit which has already been pushed to the cloud, you should use `git push --force` to avoid a merge conflict on your next push." + Example: "If you use `--amend` to modify a commit which has already been pushed to the cloud, you should use `git push --force` to avoid a merge conflict on your next push." - `tip`: Use `tip` instead of `note` when the information is not strictly necessary for basic users. \ - Example: "You can use `--amend` to update your previous commit, and `--no-edit` to avoid having to re-specify the commit message." + Example: "You can use `--amend` to update your previous commit, and `--no-edit` to avoid having to re-specify the commit message." The following admonitions should not be used: -- `hint`: `hint` is too similar to `tip` and `note`. + +- `hint`: `hint` is too similar to `tip` and `note`. - `attention`: `attention` is too similar to `warning` and `important`. - `caution`: `caution` is too similar to `warning`, `danger`, and `important`. - `error`: `error`'s use case is too niche to justify using it. - - ## Manim Bugs + ### Resolved Bugs + `angle_between_vectors`'s return type is incorrectly typed as `np.ndarray`, not `float`. `mn.Arc`'s `start_angle` is typed as `int`, not `float` (since the type of `0` defaults to `int`) "animation" is spelled "animnation" in add_animation_override docs ### Trivial Fixes + `mobject.add_updater`'s call_updater argument throws when the updater does not take dt as an argument (as updater call logic for handling dt is missing) Update: This will be resolved in the next release of manim. ### Bigger Issues + `GrowFromCenter` should probably expose introducer (like Create and Uncreate do) AnimationBuilders from .animate are not valid animations. @@ -151,12 +180,13 @@ AnimationBuilders from .animate are not valid animations. Update: These issues are being addressed by the upcoming color refactor. `Sequence[float]`, `np.ndarray`, and sometimes `Sequence[float] | np.ndarray` are used somewhat interchangably. -Since `np.ndarray` is not compatible with `Sequence[float]`, there are annoying behaviors like +Since `np.ndarray` is not compatible with `Sequence[float]`, there are annoying behaviors like the types of `line.put_start_and_end_on` not being compatible with, e.g. `line.get_start`. `remover` animations break updaters, even when used after normal animations in a `Succession`. However, this behavior goes away if `introducer` is set to `True` on the remover animation. ### Features -I would like `Add` and `Delete` type animations which add and delete objects from a scene and have a run-time of `0`. + +I would like `Add` and `Delete` type animations which add and delete objects from a scene and have a run-time of `0`. This would be useful for, e.g., creating objects in class methods which do not have access to `Scene` directly.