Skip to content

The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.

Python

Write the authoring API reference as a checked topic hierarchy

Sina Atalayc6c05dccb778
diff --git a/docs/content/reference/.nav.yml b/docs/content/reference/.nav.yml
new file mode 100644
index 00000000..e2e6443e
--- /dev/null
+++ b/docs/content/reference/.nav.yml
@@ -0,0 +1,9 @@
+nav:
+ - Overview: index.md
+ - scenes
+ - mobjects
+ - animations
+ - updaters
+ - camera-and-3d
+ - sound
+ - rendering
diff --git a/docs/content/reference/animations/.nav.yml b/docs/content/reference/animations/.nav.yml
new file mode 100644
index 00000000..d486efee
--- /dev/null
+++ b/docs/content/reference/animations/.nav.yml
@@ -0,0 +1,10 @@
+title: "Animations"
+nav:
+ - Overview: index.md
+ - animate.md
+ - rate-functions.md
+ - appear-and-disappear.md
+ - transforms.md
+ - move-and-deform.md
+ - emphasis.md
+ - together-and-in-turn.md
diff --git a/docs/content/reference/animations/animate.md b/docs/content/reference/animations/animate.md
new file mode 100644
index 00000000..d0b50699
--- /dev/null
+++ b/docs/content/reference/animations/animate.md
@@ -0,0 +1,45 @@
+---
+title: "Animate a change"
+description: "Put `.animate` before a method, and play animates the change it makes; or move a mobject to a target, or back to a saved state."
+---
+
+# Animate a change
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class AnimateHero(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=0.5)
+ self.play(m.Create(square))
+ self.play(square.animate.shift(3 * m.RIGHT).set_color(m.YELLOW))
+ self.play(square.animate(run_time=2).rotate(m.PI / 2).scale(0.5))
+ self.play(square.animate.move_to(m.ORIGIN).set_color(m.BLUE))
+```
+
+`square.shift(m.RIGHT)` moves the square at once. `square.animate.shift(m.RIGHT)` makes an
+animation that moves it: give it to `play`, and the square moves for the animation's run
+time. Chain several calls after `.animate`, and they happen together. Give `.animate` the
+animation keywords, `square.animate(run_time=2)`, to time it.
+
+`.animate` goes from the mobject as it is when the animation starts to the mobject as the
+calls leave it: each point travels on a straight line, unless you give a `path_arc`.
+
+::: manimgx.Mobject.animate
+ options:
+ heading_level: 2
+
+::: manimgx.Animate
+ options:
+ heading_level: 2
+
+## To a prepared state
+
+::: manimgx.MoveToTarget
+ options:
+ heading_level: 3
+
+::: manimgx.Restore
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/animations/appear-and-disappear.md b/docs/content/reference/animations/appear-and-disappear.md
new file mode 100644
index 00000000..7a087fca
--- /dev/null
+++ b/docs/content/reference/animations/appear-and-disappear.md
@@ -0,0 +1,129 @@
+---
+title: "Appear and disappear"
+description: "Bring mobjects into the scene, drawn, written, faded or grown in, and take them out again."
+---
+
+# Appear and disappear
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class AppearHero(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=0.5)
+ word = m.Text("Write", font_size=56)
+ star = m.Star(color=m.YELLOW, fill_opacity=0.5)
+ circle = m.Circle(color=m.GREEN, fill_opacity=0.5)
+ shapes = m.VGroup(square, word, star, circle).arrange(buff=0.8)
+ self.play(
+ m.Create(square),
+ m.Write(word),
+ m.GrowFromCenter(star),
+ m.FadeIn(circle, shift=m.UP),
+ )
+ self.play(
+ m.Uncreate(square),
+ m.Unwrite(word),
+ m.ShrinkToCenter(star),
+ m.FadeOut(circle, shift=m.DOWN),
+ )
+```
+
+An animation that brings a mobject in adds it to the scene as it begins: you don't add it
+first. One that takes a mobject out removes it from the scene as it ends. Between them, a
+mobject is drawn along its paths, written as by hand, faded, or grown from a point.
+
+## Draw and write
+
+::: manimgx.Create
+ options:
+ heading_level: 3
+
+::: manimgx.Uncreate
+ options:
+ heading_level: 3
+
+::: manimgx.DrawBorderThenFill
+ options:
+ heading_level: 3
+
+::: manimgx.Write
+ options:
+ heading_level: 3
+
+::: manimgx.Unwrite
+ options:
+ heading_level: 3
+
+## Fade
+
+::: manimgx.FadeIn
+ options:
+ heading_level: 3
+
+::: manimgx.FadeOut
+ options:
+ heading_level: 3
+
+## Grow and shrink
+
+::: manimgx.GrowFromCenter
+ options:
+ heading_level: 3
+
+::: manimgx.GrowFromPoint
+ options:
+ heading_level: 3
+
+::: manimgx.GrowFromEdge
+ options:
+ heading_level: 3
+
+::: manimgx.GrowArrow
+ options:
+ heading_level: 3
+
+::: manimgx.SpinInFromNothing
+ options:
+ heading_level: 3
+
+::: manimgx.ShrinkToCenter
+ options:
+ heading_level: 3
+
+::: manimgx.SpiralIn
+ options:
+ heading_level: 3
+
+## Part by part
+
+::: manimgx.ShowIncreasingSubsets
+ options:
+ heading_level: 3
+
+::: manimgx.ShowSubmobjectsOneByOne
+ options:
+ heading_level: 3
+
+## Type text
+
+::: manimgx.AddTextLetterByLetter
+ options:
+ heading_level: 3
+
+::: manimgx.RemoveTextLetterByLetter
+ options:
+ heading_level: 3
+
+::: manimgx.AddTextWordByWord
+ options:
+ heading_level: 3
+
+::: manimgx.TypeWithCursor
+ options:
+ heading_level: 3
+
+::: manimgx.UntypeWithCursor
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/animations/emphasis.md b/docs/content/reference/animations/emphasis.md
new file mode 100644
index 00000000..66ca9c02
--- /dev/null
+++ b/docs/content/reference/animations/emphasis.md
@@ -0,0 +1,60 @@
+---
+title: "Emphasis"
+description: "Draw the eye to a mobject: indicate it, circle it, flash a point, wiggle it, blink it."
+---
+
+# Emphasis
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class EmphasisHero(m.Scene):
+ def construct(self) -> None:
+ formula = m.MathTex("a^2", "+", "b^2", "=", "c^2", font_size=96)
+ self.add(formula)
+ self.play(m.Indicate(formula[0]))
+ self.play(m.Circumscribe(formula[2], color=m.YELLOW))
+ self.play(m.Flash(formula[4], color=m.YELLOW, flash_radius=0.8))
+ self.play(m.Wiggle(formula))
+ self.wait()
+```
+
+These animations change a mobject for a moment and give it back as it was: they point a
+viewer's eye at it while the voice talks about it.
+
+::: manimgx.Indicate
+ options:
+ heading_level: 2
+
+::: manimgx.Circumscribe
+ options:
+ heading_level: 2
+
+::: manimgx.Flash
+ options:
+ heading_level: 2
+
+::: manimgx.FocusOn
+ options:
+ heading_level: 2
+
+::: manimgx.Wiggle
+ options:
+ heading_level: 2
+
+::: manimgx.ShowPassingFlash
+ options:
+ heading_level: 2
+
+::: manimgx.ShowPassingFlashWithThinningStrokeWidth
+ options:
+ heading_level: 2
+
+::: manimgx.Blink
+ options:
+ heading_level: 2
+
+::: manimgx.Broadcast
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/animations/index.md b/docs/content/reference/animations/index.md
new file mode 100644
index 00000000..aaf89503
--- /dev/null
+++ b/docs/content/reference/animations/index.md
@@ -0,0 +1,107 @@
+---
+title: "Animations"
+description: "What changes mobjects over time: how long a change takes, how it paces itself, and every kind of animation."
+---
+
+# Animations
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class AnimationsHero(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=0.5)
+ circle = m.Circle(color=m.PINK, fill_opacity=0.5)
+ self.play(m.Create(square))
+ self.play(square.animate.shift(2 * m.LEFT).rotate(m.PI / 4))
+ self.play(m.Transform(square, circle))
+ self.play(m.Indicate(square))
+ self.play(square.animate.set_color(m.YELLOW).shift(2 * m.RIGHT))
+ self.wait()
+```
+
+An animation changes mobjects over time. [play][manimgx.Scene.play] plays it: the scene's
+time runs for the animation's `run_time` (1 second unless you give another), and every
+frame shows the change at that moment. Its `rate_func` paces it: slowly, then fast, then
+slowly, unless you give another.
+
+Any change a method makes animates: put `.animate` before the method,
+`self.play(square.animate.shift(m.RIGHT))`. The animations below make the changes a method
+can't: draw a shape in, write a text, turn one mobject into another, flash a point. Several
+play together in one `play`, or one after another in a group.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:AnimateHero)
+
+ [**Animate a change**](animate.md)
+
+ ---
+
+ `.animate`: any method call, animated. Move to a target, or back to a saved state.
+
+- ![](film:RateFunctionsHero)
+
+ [**Rate functions**](rate-functions.md)
+
+ ---
+
+ How an animation paces itself: smoothly, steadily, with a bounce or a wiggle.
+
+- ![](film:AppearHero)
+
+ [**Appear and disappear**](appear-and-disappear.md)
+
+ ---
+
+ Draw, write, fade and grow mobjects in, and take them out again.
+
+- ![](film:TransformsHero)
+
+ [**Transforms**](transforms.md)
+
+ ---
+
+ Turn one mobject into another, match the parts of two formulas, swap places.
+
+- ![](film:MoveAndDeformHero)
+
+ [**Move and deform**](move-and-deform.md)
+
+ ---
+
+ Turn about a point, follow a path, or carry every point through a function.
+
+- ![](film:EmphasisHero)
+
+ [**Emphasis**](emphasis.md)
+
+ ---
+
+ Draw the eye: indicate, circumscribe, flash, wiggle.
+
+- ![](film:TogetherHero)
+
+ [**Together and in turn**](together-and-in-turn.md)
+
+ ---
+
+ Play animations at once, one after another, or each shortly after the last.
+
+</div>
+
+## The animation
+
+Every animation takes the animation keywords: how long it runs, how it paces itself, and how
+its parts start one after another.
+
+::: manimgx.animation.timeline.AnimationOptions
+ options:
+ heading_level: 3
+ inherited_members: true
+ members: [run_time, rate_func, lag_ratio, reverse_rate_function, remover, introducer, suspend_mobject_updating, use_override, name]
+
+::: manimgx.Animation
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/animations/move-and-deform.md b/docs/content/reference/animations/move-and-deform.md
new file mode 100644
index 00000000..bde41485
--- /dev/null
+++ b/docs/content/reference/animations/move-and-deform.md
@@ -0,0 +1,86 @@
+---
+title: "Move and deform"
+description: "Turn a mobject about a point, move it along a path, or carry every point through a function, a matrix or a flow."
+---
+
+# Move and deform
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+class MoveAndDeformHero(m.Scene):
+ def construct(self) -> None:
+ grid = m.NumberPlane(
+ x_range=[-4, 4, 1], y_range=[-3, 3, 1]
+ ).prepare_for_nonlinear_transform()
+ self.add(grid)
+ self.play(m.ApplyMatrix([[1, 1], [0, 1]], grid), run_time=2)
+ self.play(
+ m.ApplyFunction(
+ lambda mob: mob.apply_function(
+ lambda p: p + 0.3 * np.array([np.sin(p[1]), np.sin(p[0]), 0])
+ ),
+ grid,
+ ),
+ run_time=2,
+ )
+ self.wait()
+```
+
+Some changes are not a method call: a turn about a point that the mobject keeps turning
+around, a trip along a path, a deformation of every point. These animations make them.
+
+## Turn and follow
+
+::: manimgx.Rotate
+ options:
+ heading_level: 3
+
+::: manimgx.Rotating
+ options:
+ heading_level: 3
+
+::: manimgx.MoveAlongPath
+ options:
+ heading_level: 3
+
+## Through a function
+
+Each point of the mobject goes where a function sends it. Curved images need more points:
+insert curves first (see [insert_n_curves][manimgx.VMobject.insert_n_curves]).
+
+::: manimgx.ApplyFunction
+ options:
+ heading_level: 3
+
+::: manimgx.ApplyPointwiseFunction
+ options:
+ heading_level: 3
+
+::: manimgx.ApplyMatrix
+ options:
+ heading_level: 3
+
+::: manimgx.ApplyComplexFunction
+ options:
+ heading_level: 3
+
+## Deform over time
+
+::: manimgx.Homotopy
+ options:
+ heading_level: 3
+
+::: manimgx.ComplexHomotopy
+ options:
+ heading_level: 3
+
+::: manimgx.ApplyWave
+ options:
+ heading_level: 3
+
+::: manimgx.PhaseFlow
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/animations/rate-functions.md b/docs/content/reference/animations/rate-functions.md
new file mode 100644
index 00000000..f14cacca
--- /dev/null
+++ b/docs/content/reference/animations/rate-functions.md
@@ -0,0 +1,253 @@
+---
+title: "Rate functions"
+description: "How an animation paces itself: smoothly, steadily, with a rush, a bounce or a wiggle. Every rate function, to play and to scrub."
+---
+
+# Rate functions { #manimgx.animation.easing }
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class RateFunctionsHero(m.Scene):
+ def construct(self) -> None:
+ rates = [m.smooth, m.linear, m.rush_into, m.there_and_back, m.ease_out_bounce]
+ names = ["smooth", "linear", "rush_into", "there_and_back", "ease_out_bounce"]
+ rows = m.VGroup()
+ for name in names:
+ label = m.Text(name, font="monospace", font_size=28)
+ dot = m.Dot(radius=0.14, color=m.YELLOW)
+ rows.add(m.VGroup(label, dot))
+ rows.arrange(m.DOWN, buff=0.5)
+ for row in rows:
+ row[0].move_to([-2.2, row.get_y(), 0], aligned_edge=m.RIGHT)
+ row[1].move_to([-1.4, row.get_y(), 0])
+ self.add(rows)
+ self.play(
+ *[
+ row[1].animate(rate_func=rate).shift(7 * m.RIGHT)
+ for row, rate in zip(rows, rates, strict=True)
+ ],
+ run_time=3,
+ )
+ self.wait()
+```
+
+An animation runs from 0, its start, to 1, its end. Its rate function says how far along the
+change is at each moment of that time: `rate_func(t)` for t from 0 to 1. The default,
+[smooth][manimgx.smooth], starts slowly, speeds up and ends slowly; [linear][manimgx.linear]
+keeps one speed. Give another to `play` or to any animation:
+`self.play(square.animate.shift(m.RIGHT), rate_func=m.rush_into)`.
+
+A rate function may go past 1 and back, for a bounce, or come back to 0, so that the
+animation ends where it started. Choose one to see it move:
+
+<div class="mx-rates" data-rates="smooth linear rush_into rush_from slow_into double_smooth there_and_back there_and_back_with_pause running_start lingering wiggle exponential_decay smoothstep smootherstep ease_in_back ease_in_bounce ease_in_circ ease_in_cubic ease_in_elastic ease_in_expo ease_in_out_back ease_in_out_bounce ease_in_out_circ ease_in_out_cubic ease_in_out_elastic ease_in_out_expo ease_in_out_quad ease_in_out_quart ease_in_out_quint ease_in_out_sine ease_in_quad ease_in_quart ease_in_quint ease_in_sine ease_out_back ease_out_bounce ease_out_circ ease_out_cubic ease_out_elastic ease_out_expo ease_out_quad ease_out_quart ease_out_quint ease_out_sine"></div>
+
+## The usual ones
+
+::: manimgx.smooth
+ options:
+ heading_level: 3
+
+::: manimgx.linear
+ options:
+ heading_level: 3
+
+::: manimgx.rush_into
+ options:
+ heading_level: 3
+
+::: manimgx.rush_from
+ options:
+ heading_level: 3
+
+::: manimgx.slow_into
+ options:
+ heading_level: 3
+
+::: manimgx.double_smooth
+ options:
+ heading_level: 3
+
+::: manimgx.there_and_back
+ options:
+ heading_level: 3
+
+::: manimgx.there_and_back_with_pause
+ options:
+ heading_level: 3
+
+::: manimgx.running_start
+ options:
+ heading_level: 3
+
+::: manimgx.lingering
+ options:
+ heading_level: 3
+
+::: manimgx.wiggle
+ options:
+ heading_level: 3
+
+::: manimgx.exponential_decay
+ options:
+ heading_level: 3
+
+::: manimgx.smoothstep
+ options:
+ heading_level: 3
+
+::: manimgx.smootherstep
+ options:
+ heading_level: 3
+
+## Easing curves
+
+The easing curves are the web's: each eases in (starts slowly), eases out (ends slowly), or
+both, with a curve of its own.
+
+<div class="mx-rows" markdown>
+
+::: manimgx.ease_in_back
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_bounce
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_circ
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_cubic
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_elastic
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_expo
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_back
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_bounce
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_circ
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_cubic
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_elastic
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_expo
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_quad
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_quart
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_quint
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_out_sine
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_quad
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_quart
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_quint
+ options:
+ heading_level: 3
+
+::: manimgx.ease_in_sine
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_back
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_bounce
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_circ
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_cubic
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_elastic
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_expo
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_quad
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_quart
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_quint
+ options:
+ heading_level: 3
+
+::: manimgx.ease_out_sine
+ options:
+ heading_level: 3
+
+</div>
+
+## Make your own
+
+A rate function is any Python function from a number to a number. These make one from
+another.
+
+::: manimgx.squish_rate_func
+ options:
+ heading_level: 3
+
+::: manimgx.not_quite_there
+ options:
+ heading_level: 3
+
+::: manimgx.unit_interval
+ options:
+ heading_level: 3
+
+::: manimgx.zero
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/animations/together-and-in-turn.md b/docs/content/reference/animations/together-and-in-turn.md
new file mode 100644
index 00000000..273097a0
--- /dev/null
+++ b/docs/content/reference/animations/together-and-in-turn.md
@@ -0,0 +1,55 @@
+---
+title: "Together and in turn"
+description: "Play animations at once, one after another, or each shortly after the one before it; slow down or speed up a play."
+---
+
+# Together and in turn
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class TogetherHero(m.Scene):
+ def construct(self) -> None:
+ dots = m.VGroup(*[m.Dot(radius=0.2, color=m.YELLOW) for _ in range(6)]).arrange(
+ buff=0.8
+ )
+ self.play(
+ m.LaggedStart(*[m.GrowFromCenter(dot) for dot in dots], lag_ratio=0.3)
+ )
+ self.play(m.Succession(*[dot.animate.shift(m.UP) for dot in dots], run_time=2))
+ self.play(m.AnimationGroup(*[dot.animate.shift(m.DOWN) for dot in dots]))
+ self.wait()
+```
+
+`self.play(a, b)` plays a and b together. A group plays animations as one: together, one
+after another, or each a little after the one before it. A group is an animation itself, so
+groups nest, and a group plays inside a larger play.
+
+::: manimgx.AnimationGroup
+ options:
+ heading_level: 2
+
+::: manimgx.Succession
+ options:
+ heading_level: 2
+
+::: manimgx.LaggedStart
+ options:
+ heading_level: 2
+
+::: manimgx.LaggedStartMap
+ options:
+ heading_level: 2
+
+::: manimgx.ChangeSpeed
+ options:
+ heading_level: 2
+
+::: manimgx.Wait
+ options:
+ heading_level: 2
+
+::: manimgx.Add
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/animations/transforms.md b/docs/content/reference/animations/transforms.md
new file mode 100644
index 00000000..87113765
--- /dev/null
+++ b/docs/content/reference/animations/transforms.md
@@ -0,0 +1,123 @@
+---
+title: "Transforms"
+description: "Turn one mobject into another: its shape and its style, part by part or by matching parts, along a straight path or an arc."
+---
+
+# Transforms
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class TransformsHero(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=0.5).shift(3 * m.LEFT)
+ circle = m.Circle(color=m.PINK, fill_opacity=0.5).shift(3 * m.LEFT)
+ star = m.Star(color=m.YELLOW, fill_opacity=0.5).shift(3 * m.RIGHT)
+ self.play(m.Create(square))
+ self.play(m.ReplacementTransform(square, circle))
+ self.play(m.TransformFromCopy(circle, star, path_arc=m.PI / 2))
+ self.play(m.Swap(circle, star))
+ self.wait()
+```
+
+A transform turns one mobject into another: its points travel to the other's, and its style
+blends into the other's. [ReplacementTransform][manimgx.ReplacementTransform] then puts the
+other mobject in its place, so that you go on with the new one;
+[Transform][manimgx.Transform] keeps the first mobject, now in the other's shape. To turn a
+formula into another, part by part, match their parts:
+[TransformMatchingTex][manimgx.TransformMatchingTex].
+
+Each point travels on a straight line unless you give an arc: `path_arc=m.PI` sends each
+point around half a circle. A path function chooses any other way.
+
+::: manimgx.Transform
+ options:
+ heading_level: 2
+
+::: manimgx.ReplacementTransform
+ options:
+ heading_level: 2
+
+::: manimgx.TransformFromCopy
+ options:
+ heading_level: 2
+
+::: manimgx.ClockwiseTransform
+ options:
+ heading_level: 2
+
+::: manimgx.CounterclockwiseTransform
+ options:
+ heading_level: 2
+
+::: manimgx.FadeTransform
+ options:
+ heading_level: 2
+
+::: manimgx.FadeTransformPieces
+ options:
+ heading_level: 2
+
+## Match the parts
+
+::: manimgx.TransformMatchingTex
+ options:
+ heading_level: 3
+
+::: manimgx.TransformMatchingShapes
+ options:
+ heading_level: 3
+
+## Trade places
+
+::: manimgx.Swap
+ options:
+ heading_level: 3
+
+::: manimgx.CyclicReplace
+ options:
+ heading_level: 3
+
+## The transform keywords
+
+::: manimgx.animation.transform.TransformOptions
+ options:
+ heading_level: 3
+
+## Paths
+
+A path function says how each point travels from where it starts to where it ends: give one
+as `path_func`.
+
+::: manimgx.straight_path
+ options:
+ heading_level: 3
+
+::: manimgx.path_along_arc
+ options:
+ heading_level: 3
+
+::: manimgx.clockwise_path
+ options:
+ heading_level: 3
+
+::: manimgx.counterclockwise_path
+ options:
+ heading_level: 3
+
+::: manimgx.spiral_path
+ options:
+ heading_level: 3
+
+::: manimgx.path_along_circles
+ options:
+ heading_level: 3
+
+::: manimgx.Path
+ options:
+ heading_level: 3
+
+::: manimgx.STRAIGHT_PATH_THRESHOLD
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/camera-and-3d/.nav.yml b/docs/content/reference/camera-and-3d/.nav.yml
new file mode 100644
index 00000000..ca3e577d
--- /dev/null
+++ b/docs/content/reference/camera-and-3d/.nav.yml
@@ -0,0 +1,7 @@
+title: "Camera and 3D"
+nav:
+ - Overview: index.md
+ - camera.md
+ - three-d-scenes.md
+ - surfaces-and-solids.md
+ - lights-and-materials.md
diff --git a/docs/content/reference/camera-and-3d/camera.md b/docs/content/reference/camera-and-3d/camera.md
new file mode 100644
index 00000000..2a5fe7a4
--- /dev/null
+++ b/docs/content/reference/camera-and-3d/camera.md
@@ -0,0 +1,137 @@
+---
+title: "Camera"
+description: "The camera's frame, to pan and zoom; the look of the picture; and the mobjects that stay fixed on the screen."
+---
+
+# Camera
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class CameraHero(m.Scene):
+ def construct(self) -> None:
+ circle = m.Circle(radius=3, color=m.BLUE)
+ tangent = m.Line(4 * m.LEFT, 4 * m.RIGHT, color=m.YELLOW).shift(3 * m.UP)
+ self.add(circle, tangent)
+ frame = self.camera.frame
+ self.play(frame.animate.scale(0.25).move_to(3 * m.UP), run_time=2)
+ self.wait()
+ self.play(frame.animate.scale(4).move_to(m.ORIGIN), run_time=2)
+```
+
+Every scene has a camera, `self.camera`. Its frame, `self.camera.frame`, is a mobject: move
+it to pan, scale it to zoom, and animate it as any other mobject. A frame half as large
+shows everything twice as large.
+
+The camera also sets the picture's look: its background, and, for 3D, its exposure, its
+tone mapping, its bloom and its shadows.
+
+::: manimgx.Camera
+ options:
+ heading_level: 2
+ members: false
+
+## The frame
+
+::: manimgx.Camera.frame
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.frame_center
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.frame_width
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.frame_height
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.auto_zoom
+ options:
+ heading_level: 3
+
+## The look
+
+::: manimgx.Camera.background_color
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.background_opacity
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.exposure
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.tone_mapping
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.bloom
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.ambient_occlusion
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.ambient_occlusion_radius
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.light_source
+ options:
+ heading_level: 3
+
+## Fixed on the screen
+
+::: manimgx.Camera.fixed_in_frame_mobjects
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.add_fixed_in_frame_mobjects
+ options:
+ heading_level: 3
+
+## Its angles, in 3D
+
+::: manimgx.Camera.three_d
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.get_phi
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.get_theta
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.get_gamma
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.get_zoom
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.get_focal_distance
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.set_phi
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.set_theta
+ options:
+ heading_level: 3
+
+::: manimgx.Camera.set_gamma
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/camera-and-3d/index.md b/docs/content/reference/camera-and-3d/index.md
new file mode 100644
index 00000000..f5fd8dd5
--- /dev/null
+++ b/docs/content/reference/camera-and-3d/index.md
@@ -0,0 +1,66 @@
+---
+title: "Camera and 3D"
+description: "What the frame shows: pan and zoom over a flat scene, or look at a three-dimensional one from any angle, lit by lights."
+---
+
+# Camera and 3D
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class CameraAnd3DHero(m.ThreeDScene):
+ def construct(self) -> None:
+ self.set_camera_orientation(phi=70 * m.DEGREES, theta=-45 * m.DEGREES)
+ axes = m.ThreeDAxes(x_range=[-3, 3], y_range=[-3, 3], z_range=[-2, 2])
+ sphere = m.Sphere(radius=1.2, resolution=(32, 32)).set_color(m.BLUE)
+ torus = m.Torus(major_radius=2.2, minor_radius=0.2).set_color(m.YELLOW)
+ self.add(m.SunLight(4 * m.UP + 3 * m.OUT), m.AmbientLight(intensity=0.3))
+ self.add(axes, sphere, torus)
+ self.begin_ambient_camera_rotation(rate=0.4)
+ self.wait(4)
+```
+
+The camera decides what the video shows. Its frame is a rectangle in the scene: the frame
+that positions are measured in. Move the frame, and the view moves with it; scale it, and
+the view zooms. In three dimensions, the camera looks at the frame from an angle that you
+choose, and turns around it while the scene plays.
+
+Every mobject has three coordinates, so flat mobjects show in 3D too. Surfaces and solids are
+made for it, and lights shade them.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:CameraHero)
+
+ [**Camera**](camera.md)
+
+ ---
+
+ The frame: pan and zoom. The look of the picture, and what stays fixed on the screen.
+
+- ![](film:ThreeDScenesHero)
+
+ [**3D scenes**](three-d-scenes.md)
+
+ ---
+
+ Look at a scene from any angle, move the camera, turn it around the scene.
+
+- ![](film:SurfacesHero)
+
+ [**Surfaces and solids**](surfaces-and-solids.md)
+
+ ---
+
+ Surfaces of functions, spheres, tori, cylinders, cones, cubes and polyhedra.
+
+- ![](film:LightsHero)
+
+ [**Lights and materials**](lights-and-materials.md)
+
+ ---
+
+ Sun, bulbs, spotlights and the sky, and how surfaces reflect them.
+
+</div>
diff --git a/docs/content/reference/camera-and-3d/lights-and-materials.md b/docs/content/reference/camera-and-3d/lights-and-materials.md
new file mode 100644
index 00000000..00564f32
--- /dev/null
+++ b/docs/content/reference/camera-and-3d/lights-and-materials.md
@@ -0,0 +1,72 @@
+---
+title: "Lights and materials"
+description: "The lights of a 3D scene, from the sun to a spotlight, and the materials that say how a surface reflects them."
+---
+
+# Lights and materials
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class LightsHero(m.ThreeDScene):
+ def construct(self) -> None:
+ self.set_camera_orientation(phi=70 * m.DEGREES, theta=-45 * m.DEGREES)
+ self.add(m.SunLight(5 * m.UP + 3 * m.OUT), m.AmbientLight(intensity=0.2))
+ spheres = m.Group()
+ for roughness in [0.2, 0.5, 0.9]:
+ sphere = m.Sphere(radius=0.8, resolution=(48, 48)).set_color(m.GOLD)
+ spheres.add(
+ sphere.set_material(m.Material(metallic=1, roughness=roughness))
+ )
+ spheres.arrange(buff=0.6)
+ self.add(spheres)
+ self.wait()
+```
+
+A 3D scene is lit by its lights: add them as you add mobjects. A sun lights everything from
+one direction; a bulb lights around it, fading with distance; a spotlight lights a cone; the
+sky lights everything a little, from all around. Without lights, a scene keeps Manim's
+plain shading.
+
+A mobject's material says how its surface reflects light: rough or smooth, plastic or metal.
+
+## Lights
+
+::: manimgx.Light
+ options:
+ heading_level: 3
+
+::: manimgx.SunLight
+ options:
+ heading_level: 3
+
+::: manimgx.PointLight
+ options:
+ heading_level: 3
+
+::: manimgx.SpotLight
+ options:
+ heading_level: 3
+
+::: manimgx.AmbientLight
+ options:
+ heading_level: 3
+
+::: manimgx.EnvironmentLight
+ options:
+ heading_level: 3
+
+## Materials
+
+::: manimgx.Material
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_material
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.set_shade_in_3d
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/camera-and-3d/surfaces-and-solids.md b/docs/content/reference/camera-and-3d/surfaces-and-solids.md
new file mode 100644
index 00000000..301f1f0b
--- /dev/null
+++ b/docs/content/reference/camera-and-3d/surfaces-and-solids.md
@@ -0,0 +1,120 @@
+---
+title: "Surfaces and solids"
+description: "Surfaces of functions, spheres, tori, cylinders, cones, cubes and polyhedra, lines and arrows in space, and meshes."
+---
+
+# Surfaces and solids { #manimgx.mobjects.three_d }
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class SurfacesHero(m.ThreeDScene):
+ def construct(self) -> None:
+ self.set_camera_orientation(phi=65 * m.DEGREES, theta=-50 * m.DEGREES)
+ shapes = m.Group(
+ m.Sphere(radius=0.9),
+ m.Torus(major_radius=0.8, minor_radius=0.3),
+ m.Cylinder(radius=0.7, height=1.6),
+ m.Cone(base_radius=0.8, height=1.6),
+ m.Cube(side_length=1.4),
+ m.Icosahedron(edge_length=1.2),
+ )
+ shapes.arrange_in_grid(rows=2, buff=0.9)
+ self.add(m.SunLight(4 * m.UP + 3 * m.OUT), m.AmbientLight(intensity=0.3))
+ self.play(m.LaggedStart(*[m.FadeIn(shape) for shape in shapes], lag_ratio=0.15))
+ self.wait()
+```
+
+A surface is the set of points a function of two numbers makes: `func(u, v)` for u and v over
+their ranges. A sphere, a torus, a cylinder and a cone are surfaces with their functions
+made for you. A solid with flat faces is a polyhedron, from a cube to an icosahedron. All
+show in a [3D scene](three-d-scenes.md), shaded by its lights.
+
+## Surfaces
+
+::: manimgx.Surface
+ options:
+ heading_level: 3
+
+::: manimgx.Sphere
+ options:
+ heading_level: 3
+
+::: manimgx.Torus
+ options:
+ heading_level: 3
+
+::: manimgx.Cylinder
+ options:
+ heading_level: 3
+ inherited_members: [set_direction]
+
+::: manimgx.Cone
+ options:
+ heading_level: 3
+ inherited_members: [set_direction]
+
+## Solids
+
+::: manimgx.Cube
+ options:
+ heading_level: 3
+
+::: manimgx.Prism
+ options:
+ heading_level: 3
+
+::: manimgx.Polyhedron
+ options:
+ heading_level: 3
+
+::: manimgx.Tetrahedron
+ options:
+ heading_level: 3
+
+::: manimgx.Octahedron
+ options:
+ heading_level: 3
+
+::: manimgx.Dodecahedron
+ options:
+ heading_level: 3
+
+::: manimgx.Icosahedron
+ options:
+ heading_level: 3
+
+::: manimgx.ConvexHull3D
+ options:
+ heading_level: 3
+
+## Lines and points in space
+
+::: manimgx.Line3D
+ options:
+ heading_level: 3
+
+::: manimgx.Arrow3D
+ options:
+ heading_level: 3
+
+::: manimgx.Dot3D
+ options:
+ heading_level: 3
+
+## Meshes
+
+::: manimgx.MeshMobject
+ options:
+ heading_level: 3
+
+## Spherical coordinates
+
+::: manimgx.spherical_to_cartesian
+ options:
+ heading_level: 3
+
+::: manimgx.cartesian_to_spherical
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/camera-and-3d/three-d-scenes.md b/docs/content/reference/camera-and-3d/three-d-scenes.md
new file mode 100644
index 00000000..db0f2d38
--- /dev/null
+++ b/docs/content/reference/camera-and-3d/three-d-scenes.md
@@ -0,0 +1,43 @@
+---
+title: "3D scenes"
+description: "A scene seen in three dimensions: set where the camera looks from, move it in a play, turn it around the scene."
+---
+
+# 3D scenes
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+class ThreeDScenesHero(m.ThreeDScene):
+ def construct(self) -> None:
+ axes = m.ThreeDAxes(
+ x_range=[-3, 3],
+ y_range=[-3, 3],
+ z_range=[0, 2],
+ x_length=7,
+ y_length=7,
+ z_length=3,
+ )
+
+ def height(u: float, v: float) -> np.ndarray:
+ return axes.c2p(u, v, 2 * np.exp(-(u**2 + v**2) / 2))
+
+ hill = m.Surface(height, u_range=[-2.5, 2.5], v_range=[-2.5, 2.5])
+ title = m.Text("A hill", font_size=40).to_corner(m.UL)
+ self.add_fixed_in_frame_mobjects(title)
+ self.add(axes, hill)
+ self.move_camera(phi=65 * m.DEGREES, theta=-45 * m.DEGREES, run_time=2)
+ self.begin_ambient_camera_rotation(rate=0.3)
+ self.wait(3)
+```
+
+A 3D scene is a scene whose camera looks at the frame from an angle. Two angles give it:
+`phi`, from straight above (0 looks straight down, as a flat scene does), and `theta`,
+around the vertical axis. The camera stays aimed at the frame's center; it shows the scene in
+perspective, and what is nearer covers what is farther.
+
+::: manimgx.ThreeDScene
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/index.md b/docs/content/reference/index.md
new file mode 100644
index 00000000..4c70b60e
--- /dev/null
+++ b/docs/content/reference/index.md
@@ -0,0 +1,76 @@
+---
+title: "Reference"
+description: "Every part of a manimgx video, from the scene to the sound, with all that each part can do."
+---
+
+# Reference
+
+A video is a **scene**. It shows **mobjects** in its frame: shapes, text, formulas, graphs
+and surfaces. **Animations** change them over time, and **updaters** keep a rule at every
+frame. The **camera** decides what the frame shows, flat or in 3D. **Sound** and a **voice**
+play along. **Rendering** makes the video.
+
+This reference tells each part in that order, with all that it can do: [Learn](../user-guide/the-basics.md)
+teaches the same story, one idea at a time.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:ScenesHero)
+
+ [**Scenes**](scenes/index.md)
+
+ ---
+
+ A scene is one video: what happens, in order, and the plays and waits that pass its
+ time.
+
+- ![](film:MobjectsHero)
+
+ [**Mobjects**](mobjects/index.md)
+
+ ---
+
+ What a video shows: shapes, text and math, graphs, 3D, and what every one of them can
+ do.
+
+- ![](film:AnimationsHero)
+
+ [**Animations**](animations/index.md)
+
+ ---
+
+ What changes mobjects over time: draw, write, transform, move, emphasize, in turn.
+
+- ![](film:UpdatersHero)
+
+ [**Updaters**](updaters/index.md)
+
+ ---
+
+ Rules a mobject keeps at every frame, and numbers to animate them by.
+
+- ![](film:CameraAnd3DHero)
+
+ [**Camera and 3D**](camera-and-3d/index.md)
+
+ ---
+
+ Pan and zoom, look at a 3D scene from any angle, light its surfaces.
+
+- ![](film:SoundHero)
+
+ [**Sound**](sound/index.md)
+
+ ---
+
+ Sounds with animations and under the video, and a voice that explains.
+
+- ![](film:RenderingHero)
+
+ [**Rendering**](rendering/index.md)
+
+ ---
+
+ The command line, the video's size and frame rate, and rendering from Python.
+
+</div>
diff --git a/docs/content/reference/mobjects/.nav.yml b/docs/content/reference/mobjects/.nav.yml
new file mode 100644
index 00000000..df9fafc9
--- /dev/null
+++ b/docs/content/reference/mobjects/.nav.yml
@@ -0,0 +1,18 @@
+title: "Mobjects"
+nav:
+ - Overview: index.md
+ - positions.md
+ - size-and-angle.md
+ - style.md
+ - colors.md
+ - groups.md
+ - copies-and-states.md
+ - paths.md
+ - shapes
+ - annotations.md
+ - text-and-math
+ - graphs
+ - networks.md
+ - matrices-and-tables.md
+ - images-and-svg.md
+ - point-clouds.md
diff --git a/docs/content/reference/mobjects/annotations.md b/docs/content/reference/mobjects/annotations.md
new file mode 100644
index 00000000..4a71d723
--- /dev/null
+++ b/docs/content/reference/mobjects/annotations.md
@@ -0,0 +1,115 @@
+---
+title: "Annotations"
+description: "What points at, frames, labels and measures other mobjects: braces, labels, frames, underlines, crosses and angle marks."
+---
+
+# Annotations
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class AnnotationsHero(m.Scene):
+ def construct(self) -> None:
+ formula = m.MathTex(r"a^2 + b^2 = c^2", font_size=72).shift(1.5 * m.UP)
+ brace = m.Brace(formula[0][:5], m.DOWN, color=m.YELLOW)
+ note = brace.get_text("the legs")
+ frame = m.SurroundingRectangle(formula[0][6:], color=m.BLUE)
+ a, b, c = [-1.5, -3, 0], [1.5, -3, 0], [1.5, -0.8, 0]
+ triangle = m.Polygon(a, b, c, color=m.WHITE)
+ right = m.RightAngle(m.Line(b, a), m.Line(b, c), length=0.35, color=m.GREEN)
+ angle = m.Angle(m.Line(a, b), m.Line(a, c), radius=0.8, color=m.RED)
+ self.play(m.Write(formula))
+ self.play(m.GrowFromCenter(brace), m.FadeIn(note), m.Create(frame))
+ self.play(m.Create(triangle), m.Create(right), m.Create(angle))
+ self.wait()
+```
+
+An annotation points at another mobject, frames it, labels it or measures it. Most take the
+mobject when you make them and fit it: a brace as long as its side, a frame around it, a
+line under it. They don't follow it afterward; to make one follow, redraw it at every frame
+with [always_redraw][manimgx.always_redraw].
+
+## Braces
+
+::: manimgx.Brace
+ options:
+ heading_level: 3
+
+::: manimgx.BraceBetweenPoints
+ options:
+ heading_level: 3
+
+::: manimgx.ArcBrace
+ options:
+ heading_level: 3
+
+::: manimgx.BraceLabel
+ options:
+ heading_level: 3
+
+::: manimgx.BraceText
+ options:
+ heading_level: 3
+
+## Frames and marks
+
+::: manimgx.SurroundingRectangle
+ options:
+ heading_level: 3
+
+::: manimgx.BackgroundRectangle
+ options:
+ heading_level: 3
+
+::: manimgx.mobjects.annotations.FrameOptions
+ options:
+ heading_level: 3
+
+::: manimgx.Underline
+ options:
+ heading_level: 3
+
+::: manimgx.Cross
+ options:
+ heading_level: 3
+
+::: manimgx.AnnotationDot
+ options:
+ heading_level: 3
+
+## Labels
+
+::: manimgx.Label
+ options:
+ heading_level: 3
+
+::: manimgx.LabeledDot
+ options:
+ heading_level: 3
+
+::: manimgx.LabeledLine
+ options:
+ heading_level: 3
+
+::: manimgx.LabeledArrow
+ options:
+ heading_level: 3
+
+::: manimgx.LabeledPolygram
+ options:
+ heading_level: 3
+
+## Angles
+
+::: manimgx.Angle
+ options:
+ heading_level: 3
+
+::: manimgx.RightAngle
+ options:
+ heading_level: 3
+
+::: manimgx.Elbow
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/colors.md b/docs/content/reference/mobjects/colors.md
new file mode 100644
index 00000000..9a62ff90
--- /dev/null
+++ b/docs/content/reference/mobjects/colors.md
@@ -0,0 +1,106 @@
+---
+title: "Colors"
+description: "The named colors, the colors you mix, and the functions that blend, invert and choose them."
+---
+
+# Colors
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class ColorsHero(m.Scene):
+ def construct(self) -> None:
+ rows = m.VGroup()
+ for family in [
+ "BLUE",
+ "TEAL",
+ "GREEN",
+ "YELLOW",
+ "GOLD",
+ "RED",
+ "MAROON",
+ "PURPLE",
+ "GREY",
+ ]:
+ row = m.VGroup(m.Text(family, font="monospace", font_size=24))
+ for shade in "ABCDE":
+ color = m.PALETTE[f"{family}_{shade}"]
+ row.add(
+ m.Circle(radius=0.24, color=color, fill_opacity=1, stroke_width=0)
+ )
+ row.arrange(buff=0.16)
+ rows.add(row)
+ rows.arrange(m.DOWN, buff=0.16, aligned_edge=m.RIGHT)
+ self.play(
+ m.LaggedStart(
+ *[m.FadeIn(row, shift=0.2 * m.RIGHT) for row in rows], lag_ratio=0.1
+ )
+ )
+ self.wait()
+```
+
+A color is a name, such as `m.BLUE`; a hex code, such as `"#58C4DD"`; or numbers of red,
+green and blue. Each takes the place of the others wherever a color goes:
+`m.Circle(color="#58C4DD")` is `m.Circle(color=m.BLUE)`.
+
+Most named colors come in a family of five shades, from A, the lightest, to E, the darkest;
+the family's own name is its C. GRAY and GREY are two spellings of one color.
+
+## The named colors
+
+::: manimgx.drawing.paint
+ options:
+ show_root_heading: false
+ extra:
+ palette: true
+
+::: manimgx.PALETTE
+ options:
+ heading_level: 3
+
+## Make a color
+
+::: manimgx.ManimColor
+ options:
+ heading_level: 3
+
+::: manimgx.HSV
+ options:
+ heading_level: 3
+
+## Blend colors
+
+::: manimgx.interpolate_color
+ options:
+ heading_level: 3
+
+::: manimgx.color_gradient
+ options:
+ heading_level: 3
+
+::: manimgx.average_color
+ options:
+ heading_level: 3
+
+::: manimgx.invert_color
+ options:
+ heading_level: 3
+
+::: manimgx.colors_by_value
+ options:
+ heading_level: 3
+
+## Choose colors at random
+
+::: manimgx.random_color
+ options:
+ heading_level: 3
+
+::: manimgx.random_bright_color
+ options:
+ heading_level: 3
+
+::: manimgx.RandomColorGenerator
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/copies-and-states.md b/docs/content/reference/mobjects/copies-and-states.md
new file mode 100644
index 00000000..24330a87
--- /dev/null
+++ b/docs/content/reference/mobjects/copies-and-states.md
@@ -0,0 +1,63 @@
+---
+title: "Copies and states"
+description: "Copy a mobject, keep its state to return to, prepare a state to move to, or make it look like another."
+---
+
+# Copies and states
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class CopiesAndStatesHero(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=0.6)
+ self.play(m.Create(square))
+ square.save_state()
+ copy = square.copy().set_color(m.YELLOW)
+ self.play(copy.animate.shift(3 * m.RIGHT))
+ target = square.generate_target()
+ target.shift(3 * m.LEFT).rotate(m.PI / 4).set_color(m.RED)
+ self.play(m.MoveToTarget(square))
+ self.play(m.Restore(square))
+ self.wait()
+```
+
+A mobject is one object in the scene: a variable that names it names that object, and a
+change to it shows wherever it is. To have two, copy it. To change a mobject and come
+back, keep its state first. To animate a change into a state that you prepare step by step,
+make its target.
+
+::: manimgx.Mobject.copy
+ options:
+ heading_level: 2
+
+## Keep a state
+
+::: manimgx.Mobject.save_state
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.restore
+ options:
+ heading_level: 3
+
+## Prepare a state
+
+::: manimgx.Mobject.generate_target
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.target
+ options:
+ heading_level: 3
+
+## Look like another
+
+::: manimgx.Mobject.become
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_points
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/graphs/.nav.yml b/docs/content/reference/mobjects/graphs/.nav.yml
new file mode 100644
index 00000000..368ba1ab
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/.nav.yml
@@ -0,0 +1,10 @@
+title: "Graphs"
+nav:
+ - Overview: index.md
+ - axes.md
+ - plotting.md
+ - number-lines.md
+ - planes.md
+ - curves.md
+ - charts.md
+ - vector-fields.md
diff --git a/docs/content/reference/mobjects/graphs/axes.md b/docs/content/reference/mobjects/graphs/axes.md
new file mode 100644
index 00000000..e27d8834
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/axes.md
@@ -0,0 +1,120 @@
+---
+title: "Axes"
+description: "Axes with coordinates of their own, their labels and numbers, and lines from them to a point."
+---
+
+# Axes
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class AxesHero(m.Scene):
+ def construct(self) -> None:
+ axes = m.Axes(x_range=[-1, 5, 1], y_range=[-1, 4, 1], x_length=9, y_length=6)
+ axes.add_coordinates()
+ names = axes.get_axis_labels("x", "y")
+ point = axes.c2p(3, 2)
+ dot = m.Dot(point, color=m.YELLOW)
+ lines = axes.get_lines_to_point(point, color=m.YELLOW)
+ label = m.MathTex("(3, 2)", color=m.YELLOW).next_to(dot, m.UR, buff=0.15)
+ self.play(m.Create(axes), m.Write(names))
+ self.play(m.GrowFromCenter(dot), m.Create(lines), m.Write(label))
+ self.wait()
+```
+
+Axes have a range on each axis, `[start, end, step]`, and a length in the frame:
+`x_range=[-3, 3, 1]` numbers the x-axis from −3 to 3 with a tick at every unit, and
+`x_length=8` makes it 8 units long. The axes' coordinates are theirs: the point where x is 2
+and y is 4 is `axes.c2p(2, 4)`, wherever the axes are and however long.
+
+::: manimgx.Axes
+ options:
+ heading_level: 2
+ members: [x_range, y_range, x_axis, y_axis, axes]
+
+## Coordinates
+
+::: manimgx.Axes.coords_to_point
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.point_to_coords
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.polar_to_point
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_origin
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_x_unit_size
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_y_unit_size
+ options:
+ heading_level: 3
+
+## Each axis
+
+::: manimgx.Axes.get_x_axis
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_y_axis
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_z_axis
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_axis
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_axes
+ options:
+ heading_level: 3
+
+## Labels and numbers
+
+::: manimgx.Axes.add_coordinates
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_axis_labels
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_x_axis_label
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_y_axis_label
+ options:
+ heading_level: 3
+
+## Lines to a point
+
+::: manimgx.Axes.get_vertical_line
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_horizontal_line
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_lines_to_point
+ options:
+ heading_level: 3
+
+## Axes in three dimensions
+
+::: manimgx.ThreeDAxes
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/graphs/charts.md b/docs/content/reference/mobjects/graphs/charts.md
new file mode 100644
index 00000000..220c29de
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/charts.md
@@ -0,0 +1,32 @@
+---
+title: "Charts"
+description: "Bar charts that grow and change, and the sample spaces of probability."
+---
+
+# Charts
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class ChartsHero(m.Scene):
+ def construct(self) -> None:
+ chart = m.BarChart(
+ [3, 5, 2, 6, 4], bar_names=["A", "B", "C", "D", "E"], y_range=[0, 8, 2]
+ )
+ self.play(m.Create(chart))
+ self.play(chart.animate.change_bar_values([5, 2, 6, 3, 7]), run_time=2)
+ self.wait()
+```
+
+A bar chart is axes with a bar for each value, which grow and shrink as the values change. A
+sample space is a rectangle that stands for all the outcomes of a chance: divide it into
+parts whose areas are their probabilities.
+
+::: manimgx.BarChart
+ options:
+ heading_level: 2
+
+::: manimgx.SampleSpace
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/mobjects/graphs/curves.md b/docs/content/reference/mobjects/graphs/curves.md
new file mode 100644
index 00000000..d50b80e1
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/curves.md
@@ -0,0 +1,44 @@
+---
+title: "Curves"
+description: "The graph of a function, a parametric curve and an implicit curve, in the frame's own coordinates."
+---
+
+# Curves
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+def heart(t: float) -> np.ndarray:
+ x = 16 * np.sin(t) ** 3
+ y = 13 * np.cos(t) - 5 * np.cos(2 * t) - 2 * np.cos(3 * t) - np.cos(4 * t)
+ return np.array([x, y, 0]) / 6
+
+
+class CurvesHero(m.Scene):
+ def construct(self) -> None:
+ graph = m.FunctionGraph(np.sin, x_range=[-6, -1], color=m.BLUE)
+ curve = m.ParametricFunction(heart, t_range=[0, 2 * np.pi], color=m.RED)
+ circle = m.ImplicitFunction(
+ lambda x, y: (x - 4) ** 2 + y**2 - 2.25, color=m.YELLOW
+ )
+ self.play(m.Create(graph), m.Create(curve), m.Create(circle), run_time=3)
+ self.wait()
+```
+
+These curves are drawn in the frame's own coordinates: the graph of `sin` passes through
+the point `[0, 0, 0]` of the frame. To draw a graph on axes, in their coordinates, use
+[axes.plot][manimgx.Axes.plot], which makes one of these for you.
+
+::: manimgx.FunctionGraph
+ options:
+ heading_level: 2
+
+::: manimgx.ParametricFunction
+ options:
+ heading_level: 2
+
+::: manimgx.ImplicitFunction
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/mobjects/graphs/index.md b/docs/content/reference/mobjects/graphs/index.md
new file mode 100644
index 00000000..ff4ae612
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/index.md
@@ -0,0 +1,98 @@
+---
+title: "Graphs"
+description: "Axes, number lines and planes with coordinates of their own, the graphs of functions and data on them, and vector fields."
+---
+
+# Graphs { #manimgx.mobjects.plotting }
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+def wave(x: float) -> float:
+ return 1.5 * np.sin(x)
+
+
+class GraphsHero(m.Scene):
+ def construct(self) -> None:
+ axes = m.Axes(x_range=[0, 7, 1], y_range=[-2, 2, 1], x_length=10, y_length=5)
+ axes.add_coordinates()
+ graph = axes.plot(wave, color=m.BLUE)
+ area = axes.get_area(graph, x_range=[0, m.PI], opacity=0.4)
+ label = axes.get_graph_label(graph, r"1.5 \sin x", x_val=2)
+ self.play(m.Create(axes))
+ self.play(m.Create(graph), m.Write(label))
+ self.play(m.FadeIn(area))
+ self.wait()
+```
+
+Axes are a mobject with coordinates of their own. A point on axes is where its numbers are,
+not where the frame's are: [c2p][manimgx.Axes.coords_to_point] turns the axes' coordinates
+into a point of the frame, to place anything on a graph. The axes draw graphs in their own
+coordinates too: the graph of a function, a curve, the area under a graph, its slope.
+
+A number line is one axis. A number plane is axes with a grid, which fills the frame unless
+you size it. A vector field draws a direction at every point of the plane.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:AxesHero)
+
+ [**Axes**](axes.md)
+
+ ---
+
+ Axes, their coordinates, their labels and numbers, and lines to a point.
+
+- ![](film:PlottingHero)
+
+ [**Plotting**](plotting.md)
+
+ ---
+
+ The graph of a function on axes: its label, the area under it, its slope, its
+ derivative.
+
+- ![](film:NumberLinesHero)
+
+ [**Number lines**](number-lines.md)
+
+ ---
+
+ One axis: ticks, numbers and labels, on an even or a logarithmic scale.
+
+- ![](film:PlanesHero)
+
+ [**Planes**](planes.md)
+
+ ---
+
+ Grids of coordinates: the number plane, the complex plane, the polar plane.
+
+- ![](film:CurvesHero)
+
+ [**Curves**](curves.md)
+
+ ---
+
+ Graphs of functions, parametric curves and implicit curves, in the frame's own
+ coordinates.
+
+- ![](film:ChartsHero)
+
+ [**Charts**](charts.md)
+
+ ---
+
+ Bar charts, and the sample spaces of probability.
+
+- ![](film:VectorFieldsHero)
+
+ [**Vector fields**](vector-fields.md)
+
+ ---
+
+ A vector at every point: arrows, stream lines, and mobjects the field carries.
+
+</div>
diff --git a/docs/content/reference/mobjects/graphs/number-lines.md b/docs/content/reference/mobjects/graphs/number-lines.md
new file mode 100644
index 00000000..6b254ebc
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/number-lines.md
@@ -0,0 +1,52 @@
+---
+title: "Number lines"
+description: "One axis with ticks, numbers and labels, on an even or a logarithmic scale."
+---
+
+# Number lines
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class NumberLinesHero(m.Scene):
+ def construct(self) -> None:
+ line = m.NumberLine(x_range=[-3, 3, 1], length=10, include_numbers=True)
+ dot = m.Dot(line.n2p(-2), radius=0.12, color=m.YELLOW)
+ interval = m.UnitInterval(length=8, include_numbers=True).shift(2 * m.DOWN)
+ self.play(m.Create(line))
+ self.play(m.GrowFromCenter(dot))
+ self.play(dot.animate.move_to(line.n2p(2.5)), run_time=2)
+ self.play(m.Create(interval))
+ self.wait()
+```
+
+A number line is a line with a number at each of its points. Its range, `[start, end,
+step]`, gives its first and last numbers and the step between its ticks; its length is in
+the frame's units. [n2p][manimgx.NumberLine.number_to_point] turns a number into its point
+on the line, to put anything at a number.
+
+Axes are number lines too: each axis of [Axes][manimgx.Axes] is one, and takes the keywords
+below.
+
+::: manimgx.NumberLine
+ options:
+ heading_level: 2
+
+::: manimgx.UnitInterval
+ options:
+ heading_level: 2
+
+## Scales
+
+A line's scale places its numbers: evenly, or by their logarithms. Give it as `scaling`.
+
+::: manimgx.LinearBase
+ options:
+ heading_level: 3
+ inherited_members: [function, inverse_function]
+
+::: manimgx.LogBase
+ options:
+ heading_level: 3
+ inherited_members: [function, inverse_function]
diff --git a/docs/content/reference/mobjects/graphs/planes.md b/docs/content/reference/mobjects/graphs/planes.md
new file mode 100644
index 00000000..4ed48ee2
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/planes.md
@@ -0,0 +1,59 @@
+---
+title: "Planes"
+description: "Grids of coordinates that fill the frame: the number plane, the complex plane, the polar plane."
+---
+
+# Planes
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class PlanesHero(m.Scene):
+ def construct(self) -> None:
+ plane = m.ComplexPlane().add_coordinates()
+ z = m.Dot(plane.n2p(2 + 1j), color=m.YELLOW)
+ label = m.MathTex("2 + i", color=m.YELLOW).next_to(z, m.UR, buff=0.1)
+ self.play(m.Create(plane, run_time=2))
+ self.play(m.GrowFromCenter(z), m.Write(label))
+ self.play(plane.animate.apply_complex_function(lambda w: w**2 / 4), run_time=3)
+ self.wait()
+```
+
+A plane is axes with a grid: a line at every step of each axis. Unless you size it, a number
+plane fills the frame, with the frame's own coordinates, so that a point of the plane is the
+point of the frame: it is the grid to see positions by. A complex plane reads its points as
+complex numbers, and a polar plane draws circles around its center and rays out of it.
+
+A plane bends with everything on it: insert more curves first
+([prepare_for_nonlinear_transform][manimgx.NumberPlane.prepare_for_nonlinear_transform]),
+and its lines curve smoothly.
+
+::: manimgx.NumberPlane
+ options:
+ heading_level: 2
+ inherited_members: [prepare_for_nonlinear_transform]
+
+::: manimgx.ComplexPlane
+ options:
+ heading_level: 2
+
+::: manimgx.PolarPlane
+ options:
+ heading_level: 2
+
+## Complex numbers and points
+
+A point `[x, y, 0]` stands for the complex number x + yi.
+
+::: manimgx.complex_to_R3
+ options:
+ heading_level: 3
+
+::: manimgx.R3_to_complex
+ options:
+ heading_level: 3
+
+::: manimgx.complex_func_to_R3_func
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/graphs/plotting.md b/docs/content/reference/mobjects/graphs/plotting.md
new file mode 100644
index 00000000..ee6abb43
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/plotting.md
@@ -0,0 +1,124 @@
+---
+title: "Plotting"
+description: "The graph of a function on axes, in their coordinates, and what explains it: its label, the area under it, its slope, its derivative."
+---
+
+# Plotting
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+def curve(x: float) -> float:
+ return 0.25 * x**2 + 0.5
+
+
+class PlottingHero(m.Scene):
+ def construct(self) -> None:
+ axes = m.Axes(x_range=[0, 4, 1], y_range=[0, 5, 1], x_length=8, y_length=5.5)
+ axes.add_coordinates()
+ graph = axes.plot(curve, color=m.BLUE)
+ label = axes.get_graph_label(graph, r"\frac{x^2}{4} + \frac{1}{2}", x_val=3.6)
+ rectangles = axes.get_riemann_rectangles(
+ graph, x_range=[1, 3], dx=0.25, fill_opacity=0.6
+ )
+ slope = axes.get_secant_slope_group(
+ 1.5, graph, dx=1, secant_line_color=m.YELLOW
+ )
+ self.play(m.Create(axes))
+ self.play(m.Create(graph), m.Write(label))
+ self.play(
+ m.LaggedStart(
+ *[m.GrowFromEdge(r, m.DOWN) for r in rectangles], lag_ratio=0.1
+ )
+ )
+ self.play(m.FadeOut(rectangles), m.Create(slope))
+ self.wait()
+```
+
+[plot][manimgx.Axes.plot] draws the graph of a Python function of x on axes, in their
+coordinates: it is a curve, a mobject as any other, to style and animate. The axes then
+make what explains it: a label at its end, the area under it, rectangles for its integral,
+its slope at a point, the graph of its derivative.
+
+These methods make new mobjects, and add nothing: add them to the scene, or animate them.
+
+## Graphs
+
+::: manimgx.Axes.plot
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.plot_line_graph
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.plot_polar_graph
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.plot_implicit_curve
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.plot_derivative_graph
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.plot_antiderivative_graph
+ options:
+ heading_level: 3
+
+## Points on a graph
+
+::: manimgx.Axes.input_to_graph_point
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.i2gp
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.input_to_graph_coords
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_graph_label
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_T_label
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_vertical_lines_to_graph
+ options:
+ heading_level: 3
+
+## Areas
+
+::: manimgx.Axes.get_area
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_riemann_rectangles
+ options:
+ heading_level: 3
+
+## Slopes
+
+::: manimgx.Axes.slope_of_tangent
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.angle_of_tangent
+ options:
+ heading_level: 3
+
+::: manimgx.Axes.get_secant_slope_group
+ options:
+ heading_level: 3
+
+::: manimgx.mobjects.plotting.SecantSlopeGroup
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/graphs/vector-fields.md b/docs/content/reference/mobjects/graphs/vector-fields.md
new file mode 100644
index 00000000..562a269c
--- /dev/null
+++ b/docs/content/reference/mobjects/graphs/vector-fields.md
@@ -0,0 +1,44 @@
+---
+title: "Vector fields"
+description: "A vector at every point of the plane, drawn as arrows or as stream lines, and the mobjects it carries."
+---
+
+# Vector fields
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+def swirl(point: np.ndarray) -> np.ndarray:
+ x, y = point[0], point[1]
+ return np.array([-y, x, 0]) / 3 + np.array([0.3 * np.sin(y), 0, 0])
+
+
+class VectorFieldsHero(m.Scene):
+ def construct(self) -> None:
+ field = m.ArrowVectorField(swirl)
+ dots = m.VGroup(*[m.Dot([x, 0, 0], color=m.YELLOW) for x in [1, 2, 3]])
+ self.play(m.Create(field))
+ self.add(dots)
+ for dot in dots:
+ dot.add_updater(field.get_nudge_updater())
+ self.wait(3)
+```
+
+A vector field gives a vector at every point of the plane: a function from a point to a
+vector. Draw it as arrows, one at each point of a grid, or as stream lines, the paths that
+particles would follow. The field's color shows its strength. A field also moves mobjects:
+it carries them as a current carries a leaf.
+
+::: manimgx.VectorField
+ options:
+ heading_level: 2
+
+::: manimgx.ArrowVectorField
+ options:
+ heading_level: 2
+
+::: manimgx.StreamLines
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/mobjects/groups.md b/docs/content/reference/mobjects/groups.md
new file mode 100644
index 00000000..75c2f131
--- /dev/null
+++ b/docs/content/reference/mobjects/groups.md
@@ -0,0 +1,98 @@
+---
+title: "Groups"
+description: "Mobjects made of other mobjects, and the methods that add, remove, arrange and sort a mobject's parts."
+---
+
+# Groups
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class GroupsHero(m.Scene):
+ def construct(self) -> None:
+ shapes = m.VGroup(
+ m.Circle(color=m.BLUE, fill_opacity=0.5),
+ m.Square(color=m.GREEN, fill_opacity=0.5),
+ m.Triangle(color=m.YELLOW, fill_opacity=0.5),
+ m.Star(color=m.RED, fill_opacity=0.5),
+ )
+ shapes.arrange(buff=0.6)
+ self.play(m.LaggedStart(*[m.Create(shape) for shape in shapes], lag_ratio=0.2))
+ self.play(shapes.animate.arrange_in_grid(rows=2, buff=0.6))
+ self.play(shapes.animate.arrange(m.DOWN, buff=0.3).scale(0.6))
+ self.play(shapes.animate.set_color(m.TEAL))
+ self.wait()
+```
+
+A mobject can hold other mobjects, its parts. A group holds nothing else: its parts are
+what it shows. Move, scale, color or animate a group, and every part changes with it.
+
+`m.VGroup` and `m.Group` are one class, by two names: Manim CE's code writes both. A group
+is a list of its parts: `group[0]` is the first one, `group[1:3]` is a group of
+the second and the third, `len(group)` counts them, and `for part in group:` goes through
+them. Every mobject's parts work the same way: a formula's terms, a graph's axes.
+
+::: manimgx.Group
+ options:
+ heading_level: 2
+
+::: manimgx.VGroup
+ options:
+ heading_level: 2
+
+## Add and remove parts
+
+::: manimgx.Mobject.add_to_back
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.insert
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.remove
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_family
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.family_members_with_points
+ options:
+ heading_level: 3
+
+## Lay parts out
+
+::: manimgx.Mobject.arrange
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.arrange_in_grid
+ options:
+ heading_level: 3
+
+## Order parts
+
+::: manimgx.Mobject.sort
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.shuffle
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.invert
+ options:
+ heading_level: 3
+
+## Name parts
+
+::: manimgx.VDict
+ options:
+ heading_level: 3
+
+::: manimgx.index_labels
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/images-and-svg.md b/docs/content/reference/mobjects/images-and-svg.md
new file mode 100644
index 00000000..702c597d
--- /dev/null
+++ b/docs/content/reference/mobjects/images-and-svg.md
@@ -0,0 +1,49 @@
+---
+title: "Images and SVG"
+description: "Pictures from image files or arrays of pixels, and drawings read from SVG files, whose shapes are paths."
+---
+
+# Images and SVG
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+class ImagesAndSvgHero(m.Scene):
+ def construct(self) -> None:
+ x = np.linspace(-1, 1, 64)
+ pixels = np.zeros((64, 64, 3), dtype=np.uint8)
+ pixels[..., 0] = 255 * (x[None, :] + 1) / 2
+ pixels[..., 2] = 255 * (x[:, None] + 1) / 2
+ image = m.ImageMobject(pixels).scale_to_fit_height(4)
+ image.set_resampling_algorithm(m.RESAMPLING_ALGORITHMS["nearest"])
+ self.play(m.FadeIn(image))
+ self.play(image.animate.rotate(m.PI / 8).scale(0.8))
+ self.wait()
+```
+
+An image is a picture on a rectangle: read from a file (PNG, JPEG and the rest), or made from
+an array of pixels. It moves, scales, turns and fades as any mobject; its pixels stay its
+own. An SVG drawing is different: its shapes become paths, each a part to color, move and
+draw in, as a shape of manimgx's own.
+
+::: manimgx.ImageMobject
+ options:
+ heading_level: 2
+
+::: manimgx.RESAMPLING_ALGORITHMS
+ options:
+ heading_level: 3
+
+::: manimgx.constants.Resampling
+ options:
+ heading_level: 3
+
+::: manimgx.SVGMobject
+ options:
+ heading_level: 2
+
+::: manimgx.mobjects.svg.PathOptions
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/index.md b/docs/content/reference/mobjects/index.md
new file mode 100644
index 00000000..db88dbcb
--- /dev/null
+++ b/docs/content/reference/mobjects/index.md
@@ -0,0 +1,197 @@
+---
+title: "Mobjects"
+description: "What a video shows. Every mobject has a place in the frame, a size, a style and parts."
+---
+
+# Mobjects
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class MobjectsHero(m.Scene):
+ def construct(self) -> None:
+ def curve(x: float) -> float:
+ return 0.5 * x**2
+
+ axes = m.Axes(x_range=[-2, 2, 1], y_range=[0, 2, 1], x_length=3.2, y_length=2.2)
+ graph = axes.plot(curve, color=m.BLUE)
+ kinds = m.VGroup(
+ m.Square(color=m.BLUE, fill_opacity=0.5),
+ m.Star(color=m.YELLOW, fill_opacity=0.5),
+ m.Arrow(m.LEFT, m.RIGHT, color=m.GREEN),
+ m.Text("Text", font_size=64),
+ m.MathTex(r"e^{i\pi} + 1 = 0", font_size=56),
+ m.VGroup(axes, graph),
+ )
+ kinds.arrange_in_grid(rows=2, buff=(1.2, 1))
+ self.play(
+ m.LaggedStart(
+ *[m.FadeIn(kind, shift=0.3 * m.UP) for kind in kinds], lag_ratio=0.15
+ )
+ )
+ self.wait()
+```
+
+A mobject is anything a video shows: a shape, a text, a formula, a graph. Making a mobject
+doesn't show it: [add][manimgx.Scene.add] it to the scene, or [play][manimgx.Scene.play] an
+animation that brings it in.
+
+Every mobject has three things:
+
+- **Points**, which give its place and its shape. They are in units: the frame's short side
+ is 8 units, and its center is the point `[0, 0, 0]`.
+- **A style**: the color and opacity of its stroke and of its fill.
+- **Parts**, which are mobjects too: a group's members, a formula's terms, a graph's axes.
+ What you do to a mobject, you do to all its parts.
+
+Every mobject can do what the first pages tell, whatever its kind: be placed, sized and
+turned, styled, grouped and copied. The pages after them tell each kind of mobject.
+
+## What every mobject can do
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:PositionsHero)
+
+ [**Positions**](positions.md)
+
+ ---
+
+ Points and directions, and the methods that place a mobject: at a point, by another
+ mobject, at the frame's edge.
+
+- ![](film:SizeAndAngleHero)
+
+ [**Size and angle**](size-and-angle.md)
+
+ ---
+
+ Scale, stretch, turn and flip a mobject, or move every point through a function.
+
+- ![](film:StyleHero)
+
+ [**Style**](style.md)
+
+ ---
+
+ Stroke and fill, color and opacity, gradients, and what covers what.
+
+- ![](film:ColorsHero)
+
+ [**Colors**](colors.md)
+
+ ---
+
+ The named colors, and the functions that make, blend and choose colors.
+
+- ![](film:GroupsHero)
+
+ [**Groups**](groups.md)
+
+ ---
+
+ Mobjects made of mobjects: add, remove, arrange and sort the parts.
+
+- ![](film:CopiesAndStatesHero)
+
+ [**Copies and states**](copies-and-states.md)
+
+ ---
+
+ Copy a mobject, keep its state to come back to, and prepare a state to move to.
+
+- ![](film:PathsHero)
+
+ [**Paths**](paths.md)
+
+ ---
+
+ The curves a shape is made of: draw a path of your own, and find points along one.
+
+</div>
+
+## Kinds of mobjects
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:LinesAndArrows)
+
+ [**Shapes**](shapes/index.md)
+
+ ---
+
+ Lines and arrows, circles and arcs, polygons, and shapes made from other shapes.
+
+- ![](film:AnnotationsHero)
+
+ [**Annotations**](annotations.md)
+
+ ---
+
+ Braces, labels, frames, underlines and angle marks: what points at other mobjects.
+
+- ![](film:TextAndMathHero)
+
+ [**Text and math**](text-and-math/index.md)
+
+ ---
+
+ Words, formulas and numbers, set by Typst inside manimgx.
+
+- ![](film:GraphsHero)
+
+ [**Graphs**](graphs/index.md)
+
+ ---
+
+ Axes, number lines and planes, the graphs of functions and data, vector fields.
+
+- ![](film:NetworksHero)
+
+ [**Networks**](networks.md)
+
+ ---
+
+ Vertices joined by edges, laid out for you, which grow and change.
+
+- ![](film:MatricesAndTablesHero)
+
+ [**Matrices and tables**](matrices-and-tables.md)
+
+ ---
+
+ Entries in rows and columns, between brackets or between lines.
+
+- ![](film:ImagesAndSvgHero)
+
+ [**Images and SVG**](images-and-svg.md)
+
+ ---
+
+ Pictures from files or pixels, and drawings read from SVG files.
+
+- ![](film:PointCloudsHero)
+
+ [**Point clouds**](point-clouds.md)
+
+ ---
+
+ Mobjects drawn as points, each a dot of its own color.
+
+</div>
+
+## The mobject
+
+::: manimgx.Mobject
+ options:
+ heading_level: 3
+ members: false
+
+::: manimgx.Mobject.submobjects
+ options:
+ heading_level: 4
+
+::: manimgx.Mobject.name
+ options:
+ heading_level: 4
diff --git a/docs/content/reference/mobjects/matrices-and-tables.md b/docs/content/reference/mobjects/matrices-and-tables.md
new file mode 100644
index 00000000..0abd1b76
--- /dev/null
+++ b/docs/content/reference/mobjects/matrices-and-tables.md
@@ -0,0 +1,69 @@
+---
+title: "Matrices and tables"
+description: "Entries in rows and columns: matrices between brackets, tables between lines, with entries of numbers, math, text or any mobject."
+---
+
+# Matrices and tables
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class MatricesAndTablesHero(m.Scene):
+ def construct(self) -> None:
+ matrix = m.Matrix([[2, 0], [1, 3]])
+ matrix.set_column_colors(m.YELLOW, m.BLUE)
+ table = m.Table(
+ [["1", "2"], ["4", "8"]],
+ row_labels=[m.Text("x"), m.Text("2ˣ")],
+ col_labels=[m.Text("a"), m.Text("b")],
+ ).scale(0.7)
+ m.VGroup(matrix, table).arrange(buff=1.5)
+ self.play(m.Write(matrix))
+ self.play(table.create())
+ self.wait()
+```
+
+A matrix and a table hold entries in rows and columns: a matrix between brackets, a table
+between lines, with labels for its rows and columns if you give them. Give the entries as
+values, and each kind of matrix or table makes their mobjects: numbers, integers, math,
+text, or the mobjects themselves. Each row, each column and each entry is a mobject, to
+color and animate.
+
+::: manimgx.Matrix
+ options:
+ heading_level: 2
+ inherited_members: [entry, entry_config, cells, get_rows, get_columns, set_row_colors, set_column_colors]
+
+::: manimgx.DecimalMatrix
+ options:
+ heading_level: 3
+
+::: manimgx.IntegerMatrix
+ options:
+ heading_level: 3
+
+::: manimgx.MobjectMatrix
+ options:
+ heading_level: 3
+
+::: manimgx.Table
+ options:
+ heading_level: 2
+ inherited_members: [entry, entry_config, cells, get_rows, get_columns, set_row_colors, set_column_colors]
+
+::: manimgx.DecimalTable
+ options:
+ heading_level: 3
+
+::: manimgx.IntegerTable
+ options:
+ heading_level: 3
+
+::: manimgx.MathTable
+ options:
+ heading_level: 3
+
+::: manimgx.MobjectTable
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/networks.md b/docs/content/reference/mobjects/networks.md
new file mode 100644
index 00000000..530055c4
--- /dev/null
+++ b/docs/content/reference/mobjects/networks.md
@@ -0,0 +1,54 @@
+---
+title: "Networks"
+description: "Graphs in the sense of networks: vertices joined by edges, laid out for you or by hand, which grow and change as a scene plays."
+---
+
+# Networks
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class NetworksHero(m.Scene):
+ def construct(self) -> None:
+ vertices = [1, 2, 3, 4, 5, 6]
+ edges = [(1, 2), (2, 3), (3, 1), (3, 4), (4, 5), (5, 6), (6, 4)]
+ graph = m.Graph(vertices, edges, layout="spring", labels=True, layout_scale=3)
+ self.play(m.Create(graph))
+ self.play(graph.animate.change_layout("circular", layout_scale=3))
+ self.wait()
+```
+
+A network is vertices, joined by edges: a graph, as graph theory says it. (For the graph of
+a function, see [Plotting](graphs/plotting.md).) [Graph][manimgx.Graph] joins its vertices
+with lines, [DiGraph][manimgx.DiGraph] with arrows, from each edge's first vertex to its
+second. Each lays its vertices out for you (`layout="spring"`, `"circular"`, `"tree"`, …),
+or where you place them; a vertex is a dot unless you give another mobject.
+
+Both can do what follows: add and remove vertices and edges, change their layout, and read
+a network from NetworkX.
+
+::: manimgx.Graph
+ options:
+ heading_level: 2
+ members: false
+
+::: manimgx.DiGraph
+ options:
+ heading_level: 2
+ members: false
+
+::: manimgx.mobjects.graph.TipConfig
+ options:
+ heading_level: 3
+
+## What a network can do
+
+Graph and DiGraph are both made from GenericGraph, which holds what they can do.
+
+::: manimgx.mobjects.graph.GenericGraph
+ options:
+ heading_level: 3
+ extra:
+ members_only: true
+ members: [vertices, edges, add_vertices, remove_vertices, add_edges, remove_edges, change_layout, from_networkx, update_edges]
diff --git a/docs/content/reference/mobjects/paths.md b/docs/content/reference/mobjects/paths.md
new file mode 100644
index 00000000..980153ff
--- /dev/null
+++ b/docs/content/reference/mobjects/paths.md
@@ -0,0 +1,212 @@
+---
+title: "Paths"
+description: "The curves a shape is made of, how to draw a path of your own, and how to find points along one."
+---
+
+# Paths
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class PathsHero(m.Scene):
+ def construct(self) -> None:
+ path = m.VMobject(color=m.YELLOW, stroke_width=6)
+ path.start_new_path([-5, -1, 0])
+ path.add_line_to([-3, 2, 0])
+ path.add_smooth_curve_to([0, 0, 0])
+ path.add_cubic_bezier_curve_to([1, 3, 0], [3, -3, 0], [5, 1, 0])
+ anchors = m.VGroup(
+ *[m.Dot(point, color=m.BLUE) for point in path.get_anchors()]
+ )
+ dot = m.Dot(color=m.RED).move_to(path.get_start())
+ self.play(m.Create(path), run_time=2)
+ self.play(m.FadeIn(anchors))
+ self.play(m.MoveAlongPath(dot, path), run_time=2)
+ self.wait()
+```
+
+A shape is a path: curves, each from one point to the next. A curve starts at an anchor,
+bends toward two handles, and ends at the next anchor. The stroke follows the curves, and
+the fill closes each part of the path back to its start. Circles, polygons, text and graphs
+are all paths, so all of this works on them too.
+
+To draw a path of your own, make an empty `m.VMobject()`, then give it its points: as
+corners, as a smooth curve through them, or one line and curve at a time.
+
+::: manimgx.VMobject
+ options:
+ heading_level: 2
+ members: false
+
+## Draw a path
+
+::: manimgx.VMobject.set_points_as_corners
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.set_points_smoothly
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.start_new_path
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_line_to
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_points_as_corners
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_smooth_curve_to
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_cubic_bezier_curve_to
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_quadratic_bezier_curve_to
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_cubic_bezier_curve
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_cubic_bezier_curves
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.add_subpath
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.append_vectorized_mobject
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.close_path
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.is_closed
+ options:
+ heading_level: 3
+
+## Smooth or sharp
+
+::: manimgx.VMobject.make_smooth
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.make_jagged
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.insert_n_curves
+ options:
+ heading_level: 3
+
+## Along a path
+
+::: manimgx.Mobject.get_start
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_end
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_midpoint
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.point_from_proportion
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.proportion_from_point
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.get_arc_length
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.get_subcurve
+ options:
+ heading_level: 3
+
+## Which way it runs
+
+::: manimgx.VMobject.get_direction
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.reverse_direction
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.force_direction
+ options:
+ heading_level: 3
+
+## Its points
+
+::: manimgx.Mobject.points
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_points
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.reset_points
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.has_points
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.append_points
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.get_anchors
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.get_subpaths
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.get_num_curves
+ options:
+ heading_level: 3
+
+::: manimgx.bezier
+ options:
+ heading_level: 3
+
+## Paths made from paths
+
+::: manimgx.CubicBezier
+ options:
+ heading_level: 3
+
+::: manimgx.DashedVMobject
+ options:
+ heading_level: 3
+
+::: manimgx.CurvesAsSubmobjects
+ options:
+ heading_level: 3
+
+::: manimgx.VectorizedPoint
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/point-clouds.md b/docs/content/reference/mobjects/point-clouds.md
new file mode 100644
index 00000000..36eb7bf3
--- /dev/null
+++ b/docs/content/reference/mobjects/point-clouds.md
@@ -0,0 +1,39 @@
+---
+title: "Point clouds"
+description: "Mobjects drawn as points, each a dot of its own color."
+---
+
+# Point clouds
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+class PointCloudsHero(m.Scene):
+ def construct(self) -> None:
+ rng = np.random.default_rng(3)
+ angles = rng.uniform(0, 2 * np.pi, 2000)
+ radii = 3 * np.sqrt(rng.uniform(0, 1, 2000))
+ points = np.stack(
+ [radii * np.cos(angles), radii * np.sin(angles), np.zeros(2000)], axis=1
+ )
+ rgbas = np.array(
+ [m.interpolate_color(m.BLUE, m.YELLOW, r / 3).to_rgba() for r in radii]
+ )
+ cloud = m.PMobject(stroke_width=6).add_points(points, rgbas)
+ self.play(m.FadeIn(cloud))
+ self.play(m.Rotate(cloud, m.PI / 2), run_time=2)
+ self.wait()
+```
+
+A point cloud is a mobject drawn as points: each point a dot of its own color, as wide as
+the cloud's stroke. Clouds suit what is many and small: dust, stars, samples.
+
+::: manimgx.PMobject
+ options:
+ heading_level: 2
+
+::: manimgx.PointCloudDot
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/mobjects/positions.md b/docs/content/reference/mobjects/positions.md
new file mode 100644
index 00000000..4a16bb4d
--- /dev/null
+++ b/docs/content/reference/mobjects/positions.md
@@ -0,0 +1,305 @@
+---
+title: "Positions"
+description: "Where a mobject is in the frame, and the methods that move it to a point, beside another mobject or to an edge."
+---
+
+# Positions
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class PositionsHero(m.Scene):
+ def construct(self) -> None:
+ plane = m.NumberPlane(
+ background_line_style={"stroke_color": m.GREY_D, "stroke_width": 1},
+ axis_config={"stroke_color": m.GREY_B, "stroke_width": 2},
+ )
+ self.add(plane)
+ names = ["ORIGIN", "UP", "DOWN", "LEFT", "RIGHT", "UL", "UR", "DL", "DR"]
+ points = [m.ORIGIN, m.UP, m.DOWN, m.LEFT, m.RIGHT, m.UL, m.UR, m.DL, m.DR]
+ dots = m.VGroup()
+ labels = m.VGroup()
+ for name, point in zip(names, points, strict=True):
+ dot = m.Dot(2.5 * point, radius=0.12, color=m.YELLOW)
+ label = m.Text(name, font="monospace", font_size=30)
+ label.next_to(dot, m.DOWN, buff=0.2)
+ label.add_background_rectangle(opacity=1, buff=0.05)
+ dots.add(dot)
+ labels.add(label)
+ self.play(
+ m.LaggedStart(*[m.GrowFromCenter(dot) for dot in dots], lag_ratio=0.1)
+ )
+ self.play(m.FadeIn(labels))
+ self.wait()
+```
+
+Every mobject has a place in the frame. A place is a point, three numbers `[x, y, z]`,
+measured in units from the frame's center. x grows to the right, y grows upward, and z
+grows out of the screen, toward the viewer. The frame's short side is 8 units: a wide
+video shows y from −4 to 4, and x from about −7.1 to 7.1.
+
+A mobject's place is its bounding box: the smallest box, along the axes, around what it
+draws. Its center, its edges and its corners are points of that box. The methods below read
+those points, and move the mobject so that one of them goes where you say. Each method
+moves the mobject's parts with it, and gives the mobject back, so that calls chain:
+`m.Text("Title").scale(1.5).to_edge(m.UP)`.
+
+## Directions
+
+The axis directions are unit vectors; the diagonals are sums of them. Multiply a direction
+by a number, and add directions together, to make other points: `3 * m.RIGHT + 2 * m.UP`
+is `[3, 2, 0]`.
+
+<div class="mx-constants" markdown>
+
+::: manimgx.ORIGIN
+ options:
+ heading_level: 3
+
+::: manimgx.UP
+ options:
+ heading_level: 3
+
+::: manimgx.DOWN
+ options:
+ heading_level: 3
+
+::: manimgx.LEFT
+ options:
+ heading_level: 3
+
+::: manimgx.RIGHT
+ options:
+ heading_level: 3
+
+::: manimgx.UL
+ options:
+ heading_level: 3
+
+::: manimgx.UR
+ options:
+ heading_level: 3
+
+::: manimgx.DL
+ options:
+ heading_level: 3
+
+::: manimgx.DR
+ options:
+ heading_level: 3
+
+::: manimgx.IN
+ options:
+ heading_level: 3
+
+::: manimgx.OUT
+ options:
+ heading_level: 3
+
+::: manimgx.X_AXIS
+ options:
+ heading_level: 3
+
+::: manimgx.Y_AXIS
+ options:
+ heading_level: 3
+
+::: manimgx.Z_AXIS
+ options:
+ heading_level: 3
+
+</div>
+
+## Where a mobject is
+
+Each of these reads a point of the mobject's bounding box, or one of its coordinates.
+
+::: manimgx.Mobject.get_center
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_top
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_bottom
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_left
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_right
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_corner
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_critical_point
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_boundary_point
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_x
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_y
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_z
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.boundary_box
+ options:
+ heading_level: 3
+
+## Move a mobject
+
+::: manimgx.Mobject.move_to
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.shift
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.center
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_x
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_y
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_z
+ options:
+ heading_level: 3
+
+## Place a mobject by another
+
+A gap between two mobjects is a buff. These are its usual sizes.
+
+<div class="mx-constants" markdown>
+
+::: manimgx.SMALL_BUFF
+ options:
+ heading_level: 3
+
+::: manimgx.MED_SMALL_BUFF
+ options:
+ heading_level: 3
+
+::: manimgx.MED_LARGE_BUFF
+ options:
+ heading_level: 3
+
+::: manimgx.LARGE_BUFF
+ options:
+ heading_level: 3
+
+::: manimgx.DEFAULT_MOBJECT_TO_MOBJECT_BUFFER
+ options:
+ heading_level: 3
+
+::: manimgx.DEFAULT_MOBJECT_TO_EDGE_BUFFER
+ options:
+ heading_level: 3
+
+</div>
+
+::: manimgx.Mobject.next_to
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.align_to
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_x
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_y
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_z
+ options:
+ heading_level: 3
+
+## Place a mobject in the frame
+
+::: manimgx.Mobject.to_edge
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.to_corner
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.shift_onto_screen
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.is_off_screen
+ options:
+ heading_level: 3
+
+## Compute a point
+
+Points are NumPy arrays, so NumPy computes with them. These functions do what a scene
+often needs.
+
+::: manimgx.interpolate
+ options:
+ heading_level: 3
+
+::: manimgx.midpoint
+ options:
+ heading_level: 3
+
+::: manimgx.normalize
+ options:
+ heading_level: 3
+
+::: manimgx.rotate_vector
+ options:
+ heading_level: 3
+
+::: manimgx.angle_of_vector
+ options:
+ heading_level: 3
+
+::: manimgx.angle_between_vectors
+ options:
+ heading_level: 3
+
+::: manimgx.line_intersection
+ options:
+ heading_level: 3
+
+::: manimgx.perpendicular_bisector
+ options:
+ heading_level: 3
+
+::: manimgx.polylabel
+ options:
+ heading_level: 3
+
+::: manimgx.inverse_interpolate
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/shapes/.nav.yml b/docs/content/reference/mobjects/shapes/.nav.yml
new file mode 100644
index 00000000..352d7729
--- /dev/null
+++ b/docs/content/reference/mobjects/shapes/.nav.yml
@@ -0,0 +1,7 @@
+title: "Shapes"
+nav:
+ - Overview: index.md
+ - lines-and-arrows.md
+ - circles-and-arcs.md
+ - polygons.md
+ - combining-shapes.md
diff --git a/docs/content/reference/mobjects/shapes/circles-and-arcs.md b/docs/content/reference/mobjects/shapes/circles-and-arcs.md
new file mode 100644
index 00000000..b4b1b297
--- /dev/null
+++ b/docs/content/reference/mobjects/shapes/circles-and-arcs.md
@@ -0,0 +1,69 @@
+---
+title: "Circles and arcs"
+description: "Circles, dots, ellipses and arcs, and the rings and slices made from them."
+---
+
+# Circles and arcs
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class CirclesAndArcs(m.Scene):
+ def construct(self) -> None:
+ shapes = m.VGroup(
+ m.Circle(color=m.BLUE),
+ m.Dot(radius=0.3, color=m.YELLOW),
+ m.Ellipse(width=2.6, height=1.4, color=m.GREEN),
+ m.Arc(radius=1, start_angle=0, angle=3 * m.PI / 2, color=m.RED),
+ m.Annulus(inner_radius=0.5, outer_radius=1, color=m.TEAL),
+ m.Sector(radius=1.1, angle=2 * m.PI / 3, color=m.GOLD),
+ )
+ names = ["Circle", "Dot", "Ellipse", "Arc", "Annulus", "Sector"]
+ cells = m.VGroup()
+ for shape, name in zip(shapes, names, strict=True):
+ label = m.Text(name, font="monospace", font_size=30)
+ cells.add(m.VGroup(shape, label.next_to(shape, m.DOWN, buff=0.4)))
+ cells.arrange_in_grid(rows=2, buff=(1.2, 0.8))
+ self.play(m.LaggedStart(*[m.Create(cell[0]) for cell in cells], lag_ratio=0.15))
+ self.play(m.FadeIn(m.VGroup(*[cell[1] for cell in cells])))
+ self.wait()
+```
+
+A circle is an arc that goes all the way around. An arc is a part of a circle: from a start
+angle, counterclockwise through an angle. A dot is a small filled circle, to mark a point.
+A ring is the region between two circles, and a slice of it, or of a disc, is a sector.
+
+Arcs end in tips as lines do: see [Lines and arrows](lines-and-arrows.md#tips).
+
+::: manimgx.Circle
+ options:
+ heading_level: 2
+
+::: manimgx.Dot
+ options:
+ heading_level: 2
+
+::: manimgx.Ellipse
+ options:
+ heading_level: 2
+
+::: manimgx.Arc
+ options:
+ heading_level: 2
+
+::: manimgx.ArcBetweenPoints
+ options:
+ heading_level: 2
+
+::: manimgx.Annulus
+ options:
+ heading_level: 2
+
+::: manimgx.AnnularSector
+ options:
+ heading_level: 2
+
+::: manimgx.Sector
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/mobjects/shapes/combining-shapes.md b/docs/content/reference/mobjects/shapes/combining-shapes.md
new file mode 100644
index 00000000..8a1ab022
--- /dev/null
+++ b/docs/content/reference/mobjects/shapes/combining-shapes.md
@@ -0,0 +1,65 @@
+---
+title: "Combining shapes"
+description: "New shapes from old ones: their union, their intersection, their difference, a shape with holes, and the hull around points."
+---
+
+# Combining shapes
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class CombiningShapes(m.Scene):
+ def construct(self) -> None:
+ def pair() -> m.VGroup:
+ return m.VGroup(
+ m.Circle(radius=0.9).shift(0.45 * m.LEFT),
+ m.Square(side_length=1.6).shift(0.45 * m.RIGHT),
+ )
+
+ made = m.VGroup()
+ names = ["Union", "Intersection", "Difference", "Exclusion"]
+ for kind, name in zip(
+ [m.Union, m.Intersection, m.Difference, m.Exclusion], names, strict=True
+ ):
+ a, b = pair()
+ shape = kind(a, b, color=m.BLUE, fill_opacity=0.7)
+ outline = m.VGroup(a, b).set_stroke(m.GREY_B, width=2)
+ label = m.Text(name, font="monospace", font_size=26).next_to(
+ outline, m.DOWN, buff=0.4
+ )
+ made.add(m.VGroup(outline, shape, label))
+ made.arrange(buff=0.6)
+ self.play(m.LaggedStart(*[m.Create(cell[0]) for cell in made], lag_ratio=0.15))
+ self.play(m.LaggedStart(*[m.FadeIn(cell[1:]) for cell in made], lag_ratio=0.15))
+ self.wait()
+```
+
+Two shapes overlap in three regions: where only the first is, where only the second is, and
+where both are. Each of these classes makes a new path from some of those regions, styled as
+you say: the originals stay as they are. A cutout cuts holes in a shape, and a convex hull
+wraps points as a band would.
+
+::: manimgx.Union
+ options:
+ heading_level: 2
+
+::: manimgx.Intersection
+ options:
+ heading_level: 2
+
+::: manimgx.Difference
+ options:
+ heading_level: 2
+
+::: manimgx.Exclusion
+ options:
+ heading_level: 2
+
+::: manimgx.Cutout
+ options:
+ heading_level: 2
+
+::: manimgx.ConvexHull
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/mobjects/shapes/index.md b/docs/content/reference/mobjects/shapes/index.md
new file mode 100644
index 00000000..94cd1f0c
--- /dev/null
+++ b/docs/content/reference/mobjects/shapes/index.md
@@ -0,0 +1,47 @@
+---
+title: "Shapes"
+description: "Lines and arrows, circles and arcs, polygons, and shapes made from other shapes."
+---
+
+# Shapes
+
+A shape is a path: curves that a stroke draws and a fill fills (see [Paths](../paths.md)).
+Each kind of shape is a class: make one with its size, then place and style it as any
+mobject.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:LinesAndArrows)
+
+ [**Lines and arrows**](lines-and-arrows.md)
+
+ ---
+
+ Lines between points, arrows that point, vectors, and the tips that end them.
+
+- ![](film:CirclesAndArcs)
+
+ [**Circles and arcs**](circles-and-arcs.md)
+
+ ---
+
+ Circles, dots, ellipses and arcs, and the rings and slices made from them.
+
+- ![](film:PolygonsHero)
+
+ [**Polygons**](polygons.md)
+
+ ---
+
+ Shapes of straight sides, from triangles to stars, and the rectangles that frame the
+ screen.
+
+- ![](film:CombiningShapes)
+
+ [**Combining shapes**](combining-shapes.md)
+
+ ---
+
+ A shape's union, intersection or difference with another, holes, and hulls.
+
+</div>
diff --git a/docs/content/reference/mobjects/shapes/lines-and-arrows.md b/docs/content/reference/mobjects/shapes/lines-and-arrows.md
new file mode 100644
index 00000000..8714d09d
--- /dev/null
+++ b/docs/content/reference/mobjects/shapes/lines-and-arrows.md
@@ -0,0 +1,128 @@
+---
+title: "Lines and arrows"
+description: "Lines between points, arrows that point, vectors from the origin, and the tips that end them."
+---
+
+# Lines and arrows
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class LinesAndArrows(m.Scene):
+ def construct(self) -> None:
+ line = m.Line(m.LEFT, m.RIGHT)
+ dashed = m.DashedLine(m.LEFT, m.RIGHT, color=m.BLUE)
+ arrow = m.Arrow(m.LEFT, m.RIGHT, buff=0, color=m.YELLOW)
+ double = m.DoubleArrow(m.LEFT, m.RIGHT, buff=0, color=m.GREEN)
+ curved = m.CurvedArrow(m.LEFT, m.RIGHT, color=m.PINK)
+ stealth = m.Line(m.LEFT, m.RIGHT, color=m.ORANGE).add_tip(
+ tip_shape=m.StealthTip
+ )
+ shapes = m.VGroup(line, dashed, arrow, double, curved, stealth)
+ names = m.VGroup(
+ m.Text("Line", font="monospace", font_size=26),
+ m.Text("DashedLine", font="monospace", font_size=26),
+ m.Text("Arrow", font="monospace", font_size=26),
+ m.Text("DoubleArrow", font="monospace", font_size=26),
+ m.Text("CurvedArrow", font="monospace", font_size=26),
+ m.Text("StealthTip", font="monospace", font_size=26),
+ )
+ cells = m.VGroup()
+ for shape, name in zip(shapes, names, strict=True):
+ name.next_to(shape, m.DOWN, buff=0.4)
+ cells.add(m.VGroup(shape, name))
+ cells.arrange_in_grid(rows=2, buff=(1.4, 1))
+ self.play(m.LaggedStart(*[m.Create(shape) for shape in shapes], lag_ratio=0.2))
+ self.play(m.FadeIn(names))
+ self.wait()
+```
+
+A line joins two points. An arrow is a line with a tip at its end, which shows a direction;
+a vector is an arrow from the origin. Lines, arrows and arcs can end in a tip, at either end,
+in any of the shapes at the [end of this page](#tips).
+
+An end of a line can also be a mobject: the line then runs from that mobject's edge, so that
+it joins two shapes without crossing them.
+
+::: manimgx.Line
+ options:
+ heading_level: 2
+
+::: manimgx.DashedLine
+ options:
+ heading_level: 2
+
+::: manimgx.Arrow
+ options:
+ heading_level: 2
+
+::: manimgx.DoubleArrow
+ options:
+ heading_level: 2
+
+::: manimgx.Vector
+ options:
+ heading_level: 2
+
+::: manimgx.CurvedArrow
+ options:
+ heading_level: 2
+
+::: manimgx.CurvedDoubleArrow
+ options:
+ heading_level: 2
+
+::: manimgx.TangentLine
+ options:
+ heading_level: 2
+
+## Tips
+
+A tip is a small shape at the end of a line, an arc or an arrow. Arrows make theirs; any
+other line or arc takes one with `add_tip`. `tip_shape` chooses its shape, and `tip_style`
+its style.
+
+::: manimgx.TipableVMobject
+ options:
+ heading_level: 3
+ members: [add_tip, pop_tips, get_tip, get_tips, has_tip, has_start_tip, tip, start_tip, get_start, get_end, get_length]
+
+::: manimgx.mobjects.shapes.TippedBase
+ options:
+ heading_level: 3
+ inherited_members: [tip_length, normal_vector, tip_style]
+
+### Tip shapes
+
+::: manimgx.ArrowTriangleFilledTip
+ options:
+ heading_level: 4
+
+::: manimgx.ArrowTriangleTip
+ options:
+ heading_level: 4
+
+::: manimgx.StealthTip
+ options:
+ heading_level: 4
+
+::: manimgx.ArrowCircleFilledTip
+ options:
+ heading_level: 4
+
+::: manimgx.ArrowCircleTip
+ options:
+ heading_level: 4
+
+::: manimgx.ArrowSquareFilledTip
+ options:
+ heading_level: 4
+
+::: manimgx.ArrowSquareTip
+ options:
+ heading_level: 4
+
+::: manimgx.ArrowTip
+ options:
+ heading_level: 4
diff --git a/docs/content/reference/mobjects/shapes/polygons.md b/docs/content/reference/mobjects/shapes/polygons.md
new file mode 100644
index 00000000..b0a19278
--- /dev/null
+++ b/docs/content/reference/mobjects/shapes/polygons.md
@@ -0,0 +1,98 @@
+---
+title: "Polygons"
+description: "Shapes of straight sides, from triangles to stars, and the rectangles that frame the screen."
+---
+
+# Polygons
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class PolygonsHero(m.Scene):
+ def construct(self) -> None:
+ shapes = m.VGroup(
+ m.Triangle(color=m.BLUE),
+ m.Square(side_length=1.8, color=m.GREEN),
+ m.Rectangle(width=2.6, height=1.5, color=m.YELLOW),
+ m.RoundedRectangle(width=2.6, height=1.5, corner_radius=0.4, color=m.TEAL),
+ m.RegularPolygon(n=6, color=m.RED),
+ m.Star(color=m.GOLD),
+ )
+ names = [
+ "Triangle",
+ "Square",
+ "Rectangle",
+ "RoundedRectangle",
+ "RegularPolygon",
+ "Star",
+ ]
+ cells = m.VGroup()
+ for shape, name in zip(shapes, names, strict=True):
+ label = m.Text(name, font="monospace", font_size=26)
+ cells.add(m.VGroup(shape, label.next_to(shape, m.DOWN, buff=0.4)))
+ cells.arrange_in_grid(rows=2, buff=(1, 0.8))
+ self.play(m.LaggedStart(*[m.Create(cell[0]) for cell in cells], lag_ratio=0.15))
+ self.play(m.FadeIn(m.VGroup(*[cell[1] for cell in cells])))
+ self.wait()
+```
+
+A polygon is a shape of straight sides, from each corner to the next and from the last back
+to the first. Give `m.Polygon` its corners, or take a ready-made one: a triangle, a square, a
+rectangle, a regular polygon, a star. Every polygon can round its corners.
+
+A polygram is several polygons in one shape; a polygon is a polygram of one.
+
+::: manimgx.Polygon
+ options:
+ heading_level: 2
+
+::: manimgx.Polygram
+ options:
+ heading_level: 2
+
+::: manimgx.Triangle
+ options:
+ heading_level: 2
+
+::: manimgx.Square
+ options:
+ heading_level: 2
+
+::: manimgx.Rectangle
+ options:
+ heading_level: 2
+
+::: manimgx.RoundedRectangle
+ options:
+ heading_level: 2
+
+::: manimgx.RegularPolygon
+ options:
+ heading_level: 2
+
+::: manimgx.RegularPolygram
+ options:
+ heading_level: 2
+
+::: manimgx.Star
+ options:
+ heading_level: 2
+
+::: manimgx.ArcPolygon
+ options:
+ heading_level: 2
+
+::: manimgx.ArcPolygonFromArcs
+ options:
+ heading_level: 2
+
+## The screen's shape
+
+::: manimgx.ScreenRectangle
+ options:
+ heading_level: 3
+
+::: manimgx.FullScreenRectangle
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/size-and-angle.md b/docs/content/reference/mobjects/size-and-angle.md
new file mode 100644
index 00000000..891b3df7
--- /dev/null
+++ b/docs/content/reference/mobjects/size-and-angle.md
@@ -0,0 +1,146 @@
+---
+title: "Size and angle"
+description: "How large a mobject is and which way it turns, and the methods that scale, stretch, turn, flip and reshape it."
+---
+
+# Size and angle
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class SizeAndAngleHero(m.Scene):
+ def construct(self) -> None:
+ shapes = m.VGroup(
+ *[
+ m.Square(side_length=1.6, color=m.BLUE, fill_opacity=0.5)
+ for _ in range(4)
+ ]
+ )
+ shapes.arrange(buff=1.2)
+ names = m.VGroup(
+ m.Text("scale(1.4)", font="monospace", font_size=30),
+ m.Text("rotate(PI / 4)", font="monospace", font_size=30),
+ m.Text("stretch(1.6, 0)", font="monospace", font_size=30),
+ m.Text("flip()", font="monospace", font_size=30),
+ )
+ for shape, name in zip(shapes, names, strict=True):
+ name.next_to(shape, m.DOWN, buff=1.1)
+ marker = m.Dot(color=m.YELLOW).move_to(shapes[3].get_corner(m.UR))
+ shapes[3].add(marker)
+ self.add(shapes, names)
+ self.play(
+ shapes[0].animate.scale(1.4),
+ shapes[1].animate.rotate(m.PI / 4),
+ shapes[2].animate.stretch(1.6, 0),
+ shapes[3].animate.flip(),
+ run_time=2,
+ )
+ self.wait()
+```
+
+A mobject's size is its bounding box's: its [width][manimgx.Mobject.width] and its
+[height][manimgx.Mobject.height]. Most shapes take their size when you make them (a
+circle its `radius`, a text its `font_size`); these methods change it later, about the
+mobject's center unless you give another point.
+
+An angle is in radians: a whole turn is `m.TAU`, half a turn `m.PI`, and `30 * m.DEGREES`
+is 30 degrees. A positive angle turns counterclockwise.
+
+## Size
+
+::: manimgx.Mobject.width
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.height
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.scale
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.scale_to_fit_width
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.scale_to_fit_height
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_width
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_height
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.stretch
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.stretch_to_fit_width
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.stretch_to_fit_height
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.replace
+ options:
+ heading_level: 3
+
+## Angle
+
+<div class="mx-constants" markdown>
+
+::: manimgx.PI
+ options:
+ heading_level: 3
+
+::: manimgx.TAU
+ options:
+ heading_level: 3
+
+::: manimgx.DEGREES
+ options:
+ heading_level: 3
+
+</div>
+
+::: manimgx.Mobject.rotate
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.flip
+ options:
+ heading_level: 3
+
+::: manimgx.rotation_matrix
+ options:
+ heading_level: 3
+
+## Any change
+
+::: manimgx.Mobject.put_start_and_end_on
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.apply_matrix
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.apply_function
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.apply_complex_function
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/style.md b/docs/content/reference/mobjects/style.md
new file mode 100644
index 00000000..98b3edd2
--- /dev/null
+++ b/docs/content/reference/mobjects/style.md
@@ -0,0 +1,184 @@
+---
+title: "Style"
+description: "A mobject's fill and stroke, their colors and opacities, gradients, and what covers what."
+---
+
+# Style
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class StyleHero(m.Scene):
+ def construct(self) -> None:
+ stroked = m.Circle(color=m.BLUE, stroke_width=8)
+ filled = m.Circle(color=m.GREEN, fill_opacity=0.6)
+ gradient = m.Circle(fill_opacity=1, stroke_width=0).set_color(
+ [m.BLUE, m.YELLOW]
+ )
+ faint = m.Circle(color=m.RED, fill_opacity=1).fade(0.7)
+ circles = m.VGroup(stroked, filled, gradient, faint).arrange(buff=0.8)
+ names = m.VGroup(
+ m.Text("stroke", font="monospace", font_size=24),
+ m.Text("fill", font="monospace", font_size=24),
+ m.Text("gradient", font="monospace", font_size=24),
+ m.Text("fade", font="monospace", font_size=24),
+ )
+ for circle, name in zip(circles, names, strict=True):
+ name.next_to(circle, m.DOWN, buff=0.5)
+ self.play(
+ m.LaggedStart(*[m.Create(circle) for circle in circles], lag_ratio=0.2)
+ )
+ self.play(m.FadeIn(names))
+ self.wait()
+```
+
+A shape has a stroke, its outline, and a fill, its inside. Each has a color and an
+opacity, from 0 (unseen) to 1 (solid), and the stroke has a width, in hundredths of a unit.
+Most shapes are made with a stroke and no fill: give `fill_opacity` to fill them.
+
+Every mobject takes the same style keywords when you make it, and each kind sets its own
+defaults (a circle is red, a dot is filled). The methods below change the style later,
+for the mobject and all its parts.
+
+::: manimgx.drawing.paint.Style
+ options:
+ heading_level: 2
+ inherited_members: true
+ members: [color, fill_color, fill_opacity, stroke_color, stroke_opacity, stroke_width, background_stroke_color, background_stroke_opacity, background_stroke_width, sheen_factor, sheen_direction, joint_type, cap_style, shade_in_3d, material, z_index, name, target]
+
+## Color and opacity
+
+::: manimgx.Mobject.set_color
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_fill
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_stroke
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_opacity
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.fade
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.fade_to
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_style
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_style
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.match_color
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.color
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.fill_color
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.fill_opacity
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.stroke_color
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.stroke_opacity
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.stroke_width
+ options:
+ heading_level: 3
+
+## Over a source's colors
+
+Text and SVG drawings come with colors of their own. These keywords paint over them.
+
+::: manimgx.drawing.paint.Repaint
+ options:
+ heading_level: 3
+
+## Gradients and sheen
+
+A list of colors, given where one color goes, makes a gradient: `set_color([m.BLUE,
+m.YELLOW])` blends one into the other across the mobject.
+
+::: manimgx.Mobject.set_color_by_gradient
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_colors_by_radial_gradient
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_submobject_colors_by_radial_gradient
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_sheen
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.set_sheen_direction
+ options:
+ heading_level: 3
+
+## Ends and corners of a stroke
+
+::: manimgx.CapStyleType
+ options:
+ heading_level: 3
+
+::: manimgx.LineJointType
+ options:
+ heading_level: 3
+
+::: manimgx.VMobject.set_cap_style
+ options:
+ heading_level: 3
+
+## What covers what
+
+A mobject added later covers one added before. A higher z-index covers a lower one,
+whatever the order.
+
+::: manimgx.Mobject.set_z_index
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.z_index
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.add_background_rectangle
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.background_rectangle
+ options:
+ heading_level: 3
+
+## A class's defaults
+
+::: manimgx.Mobject.set_default
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/text-and-math/.nav.yml b/docs/content/reference/mobjects/text-and-math/.nav.yml
new file mode 100644
index 00000000..e5497a5a
--- /dev/null
+++ b/docs/content/reference/mobjects/text-and-math/.nav.yml
@@ -0,0 +1,6 @@
+title: "Text and math"
+nav:
+ - Overview: index.md
+ - text.md
+ - math.md
+ - numbers.md
diff --git a/docs/content/reference/mobjects/text-and-math/index.md b/docs/content/reference/mobjects/text-and-math/index.md
new file mode 100644
index 00000000..e3c95ea1
--- /dev/null
+++ b/docs/content/reference/mobjects/text-and-math/index.md
@@ -0,0 +1,63 @@
+---
+title: "Text and math"
+description: "Words, formulas, numbers and code, set by Typst inside manimgx, in fonts that come with it."
+---
+
+# Text and math
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class TextAndMathHero(m.Scene):
+ def construct(self) -> None:
+ title = m.Text("The Pythagorean theorem", font_size=56)
+ formula = m.MathTex("a^2", "+", "b^2", "=", "c^2", font_size=80)
+ formula[2].set_color(m.YELLOW)
+ number = m.DecimalNumber(
+ 3.14159, num_decimal_places=4, font_size=56, color=m.BLUE
+ )
+ lines = m.VGroup(title, formula, number).arrange(m.DOWN, buff=0.7)
+ self.play(m.Write(title))
+ self.play(m.Write(formula))
+ self.play(m.FadeIn(number))
+ self.wait()
+```
+
+manimgx sets text and formulas itself, with [Typst](https://typst.app) and the fonts that
+come with it: you install no LaTeX and no fonts, and a text looks the same on every
+computer. A text is a mobject made of its glyphs, so it moves, scales, colors and animates
+as any shape does.
+
+Write words with [Text][manimgx.Text], a formula in LaTeX with
+[MathTex][manimgx.MathTex], words with formulas in them with [Tex][manimgx.Tex], and Typst
+markup with [Typst][manimgx.Typst]. A number that changes is a
+[DecimalNumber][manimgx.DecimalNumber].
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:TextHero)
+
+ [**Text**](text.md)
+
+ ---
+
+ Words in a font, paragraphs, titles, bulleted lists and code.
+
+- ![](film:MathHero)
+
+ [**Math**](math.md)
+
+ ---
+
+ Formulas in LaTeX or Typst, and their parts, to color, move and match.
+
+- ![](film:NumbersHero)
+
+ [**Numbers**](numbers.md)
+
+ ---
+
+ Numbers written with a set number of decimal places, which can change as a scene plays.
+
+</div>
diff --git a/docs/content/reference/mobjects/text-and-math/math.md b/docs/content/reference/mobjects/text-and-math/math.md
new file mode 100644
index 00000000..7aae3af9
--- /dev/null
+++ b/docs/content/reference/mobjects/text-and-math/math.md
@@ -0,0 +1,68 @@
+---
+title: "Math"
+description: "Formulas in LaTeX or in Typst, typeset by manimgx, and the parts of a formula to color, move and match."
+---
+
+# Math
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class MathHero(m.Scene):
+ def construct(self) -> None:
+ before = m.MathTex("a^2", "+", "b^2", "=", "c^2", font_size=96)
+ after = m.MathTex("a^2", "=", "c^2", "-", "b^2", font_size=96)
+ before[2].set_color(m.YELLOW)
+ after[4].set_color(m.YELLOW)
+ self.play(m.Write(before))
+ self.play(m.TransformMatchingTex(before, after))
+ self.wait()
+```
+
+[MathTex][manimgx.MathTex] typesets a formula written in LaTeX: fractions, roots, sums and
+integrals, matrices, `cases`, Greek letters. Write it in a raw string, `r"..."`, so that
+Python keeps its backslashes. LaTeX packages and `\def` don't work; a command manimgx
+doesn't know stops the scene with its name.
+
+Give `MathTex` several strings, and each one is a part of the formula, to color, move or
+animate alone: `MathTex("a^2", "+", "b^2")[2]` is the b². Parts that are written the same
+in two formulas move into each other with
+[TransformMatchingTex][manimgx.TransformMatchingTex].
+
+[Tex][manimgx.Tex] is text with formulas in it, between `$` signs. If you know Typst, write
+it directly: [Typst][manimgx.Typst] takes Typst markup, and
+[MathTypst][manimgx.MathTypst] a formula in Typst's math syntax.
+
+::: manimgx.MathTex
+ options:
+ heading_level: 2
+
+::: manimgx.MathTexPart
+ options:
+ heading_level: 2
+
+::: manimgx.Tex
+ options:
+ heading_level: 2
+
+::: manimgx.Typst
+ options:
+ heading_level: 2
+
+::: manimgx.MathTypst
+ options:
+ heading_level: 2
+
+## A typeset text's parts
+
+Every text and formula is made of glyphs, as Typst sets them: each knows which characters of
+its source it draws. A source Typst can't set stops the scene with Typst's error.
+
+::: manimgx.mobjects.text.TypstGlyph
+ options:
+ heading_level: 3
+
+::: manimgx.drawing.typesetting.TypstError
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/text-and-math/numbers.md b/docs/content/reference/mobjects/text-and-math/numbers.md
new file mode 100644
index 00000000..9edc27a0
--- /dev/null
+++ b/docs/content/reference/mobjects/text-and-math/numbers.md
@@ -0,0 +1,53 @@
+---
+title: "Numbers"
+description: "Numbers written with a set number of decimal places, integers, and named values that follow a tracker."
+---
+
+# Numbers
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class NumbersHero(m.Scene):
+ def construct(self) -> None:
+ number = m.DecimalNumber(0, num_decimal_places=2, font_size=96, color=m.YELLOW)
+ variable = m.Variable(0, m.MathTex("x"), num_decimal_places=2).scale(1.5)
+ tracker = variable.tracker
+ m.VGroup(number, variable).arrange(m.DOWN, buff=1)
+
+ def follow(mobject: m.DecimalNumber) -> None:
+ mobject.set_value(tracker.get_value())
+
+ number.add_updater(follow)
+ self.add(number, variable)
+ self.play(tracker.animate.set_value(3.14), run_time=2)
+ self.wait()
+```
+
+A number is a text that knows its value. [set_value][manimgx.DecimalNumber.set_value] shows
+another value in its place, with the same look, so a number can count while a scene plays:
+by an [updater](../../updaters/index.md) that sets it at every frame, or by
+[ChangeDecimalToValue][manimgx.ChangeDecimalToValue].
+
+::: manimgx.DecimalNumber
+ options:
+ heading_level: 2
+
+::: manimgx.Integer
+ options:
+ heading_level: 2
+
+::: manimgx.Variable
+ options:
+ heading_level: 2
+
+## Count to a value
+
+::: manimgx.ChangeDecimalToValue
+ options:
+ heading_level: 3
+
+::: manimgx.ChangingDecimal
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/mobjects/text-and-math/text.md b/docs/content/reference/mobjects/text-and-math/text.md
new file mode 100644
index 00000000..f871d60d
--- /dev/null
+++ b/docs/content/reference/mobjects/text-and-math/text.md
@@ -0,0 +1,122 @@
+---
+title: "Text"
+description: "Words in a font, paragraphs, titles, bulleted lists and code listings."
+---
+
+# Text
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class TextHero(m.Scene):
+ def construct(self) -> None:
+ title = m.Text("Text", font_size=72)
+ styles = m.VGroup(
+ m.Text("bold", weight=m.BOLD, font_size=40),
+ m.Text("italic", slant=m.ITALIC, font_size=40),
+ m.Text("monospace", font="monospace", font_size=40),
+ m.Text("red and blue", t2c={"red": m.RED, "blue": m.BLUE}, font_size=40),
+ ).arrange(buff=0.6)
+ items = m.BulletedList("one idea", "at a time", font_size=40)
+ page = m.VGroup(title, styles, items).arrange(m.DOWN, buff=0.7)
+ self.play(m.Write(title))
+ self.play(m.LaggedStart(*[m.FadeIn(style) for style in styles], lag_ratio=0.2))
+ self.play(m.Write(items))
+ self.wait()
+```
+
+[Text][manimgx.Text] writes words exactly as you give them, in a font: a new line (`\n`)
+starts a new line. Its size is `font_size`, 48 unless you give another. Its parts are its
+characters, so `text[0]` is the first one; `t2c` colors parts of it by their words.
+
+A title, a bulleted list and a paragraph arrange lines of text for you, and a code listing
+highlights a program's source.
+
+::: manimgx.Text
+ options:
+ heading_level: 2
+
+::: manimgx.Paragraph
+ options:
+ heading_level: 2
+
+::: manimgx.Title
+ options:
+ heading_level: 2
+
+::: manimgx.BulletedList
+ options:
+ heading_level: 2
+
+::: manimgx.Code
+ options:
+ heading_level: 2
+
+::: manimgx.mobjects.code.CodeText
+ options:
+ heading_level: 3
+
+## Weights and slants
+
+A text's `weight` is how heavy its strokes are, and its `slant` how it leans.
+
+<div class="mx-constants" markdown>
+
+::: manimgx.NORMAL
+ options:
+ heading_level: 3
+
+::: manimgx.ITALIC
+ options:
+ heading_level: 3
+
+::: manimgx.OBLIQUE
+ options:
+ heading_level: 3
+
+::: manimgx.THIN
+ options:
+ heading_level: 3
+
+::: manimgx.ULTRALIGHT
+ options:
+ heading_level: 3
+
+::: manimgx.LIGHT
+ options:
+ heading_level: 3
+
+::: manimgx.SEMILIGHT
+ options:
+ heading_level: 3
+
+::: manimgx.BOOK
+ options:
+ heading_level: 3
+
+::: manimgx.MEDIUM
+ options:
+ heading_level: 3
+
+::: manimgx.SEMIBOLD
+ options:
+ heading_level: 3
+
+::: manimgx.BOLD
+ options:
+ heading_level: 3
+
+::: manimgx.ULTRABOLD
+ options:
+ heading_level: 3
+
+::: manimgx.HEAVY
+ options:
+ heading_level: 3
+
+::: manimgx.ULTRAHEAVY
+ options:
+ heading_level: 3
+
+</div>
diff --git a/docs/content/reference/rendering/.nav.yml b/docs/content/reference/rendering/.nav.yml
new file mode 100644
index 00000000..fbac21aa
--- /dev/null
+++ b/docs/content/reference/rendering/.nav.yml
@@ -0,0 +1,6 @@
+title: "Rendering"
+nav:
+ - Overview: index.md
+ - command-line.md
+ - configuration.md
+ - from-python.md
diff --git a/docs/content/reference/rendering/configuration.md b/docs/content/reference/rendering/configuration.md
new file mode 100644
index 00000000..47dece65
--- /dev/null
+++ b/docs/content/reference/rendering/configuration.md
@@ -0,0 +1,40 @@
+---
+title: "Configuration"
+description: "The configuration every scene is made and rendered with: the video's size and frame rate, its background, and the frame's size in units."
+---
+
+# Configuration
+
+```python fold title="The film's code"
+import manimgx as m
+
+m.config.pixel_width, m.config.pixel_height = 1080, 1920
+
+
+class ConfigurationHero(m.Scene):
+ def construct(self) -> None:
+ frame = m.Rectangle(
+ width=m.config.frame_width - 0.2,
+ height=m.config.frame_height - 0.2,
+ color=m.BLUE,
+ )
+ square = m.Square(side_length=8, color=m.YELLOW).scale(0.97)
+ label = m.Text("1080 × 1920", font_size=56)
+ self.play(m.Create(frame), m.Create(square), m.Write(label))
+ self.wait()
+```
+
+`m.config` holds what every scene is made with: the video's size in pixels, its frame rate,
+its background, and the frame's size in units. Set it after `import manimgx as m`, before
+the scene is made; the command line's options set it too (`-r 1080x1920`, `--fps 30`).
+
+The frame has the video's shape, and its short side is 8 units: a wide video shows about
+14.2 × 8 units, a tall one 8 × 14.2, and the 8 × 8 square in the middle is in both.
+
+::: manimgx.config.config
+ options:
+ heading_level: 2
+
+::: manimgx.config.Config
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/rendering/from-python.md b/docs/content/reference/rendering/from-python.md
new file mode 100644
index 00000000..3d89515d
--- /dev/null
+++ b/docs/content/reference/rendering/from-python.md
@@ -0,0 +1,76 @@
+---
+title: "From Python"
+description: "Render a scene from a program: its film, with its frames, plays, sounds, sections and captions, and a window that plays it."
+---
+
+# From Python
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class FromPythonHero(m.Scene):
+ def construct(self) -> None:
+ code = m.Code(
+ code_string='film = MyScene().render()\nfilm.export("video.mp4")\nprint(film.subtitles())',
+ language="python",
+ background="window",
+ ).scale(1.1)
+ self.play(m.FadeIn(code))
+ self.wait()
+```
+
+A scene renders from Python as from the command line: `MyScene().render()` runs it and
+records its film. The film keeps the frames, the plays, the sounds, the sections and the
+captions, to write as a video or to read in a program. A window plays a film on the screen as
+it is recorded.
+
+::: manimgx.Scene.render
+ options:
+ heading_level: 2
+
+::: manimgx.Film
+ options:
+ heading_level: 2
+
+::: manimgx.Window
+ options:
+ heading_level: 2
+
+## What a film holds
+
+::: manimgx.rendering.film.Frame
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.Play
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.Section
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.Export
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.Cut
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.Take
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.FrameSink
+ options:
+ heading_level: 3
+
+::: manimgx.rendering.film.PlayHook
+ options:
+ heading_level: 3
+
+::: manimgx.audio.sound.RATE
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/rendering/index.md b/docs/content/reference/rendering/index.md
new file mode 100644
index 00000000..dc36adbb
--- /dev/null
+++ b/docs/content/reference/rendering/index.md
@@ -0,0 +1,55 @@
+---
+title: "Rendering"
+description: "Make the video: the command line, the configuration a scene is made with, and rendering from Python."
+---
+
+# Rendering
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class RenderingHero(m.Scene):
+ def construct(self) -> None:
+ commands = m.Code(
+ code_string="manimgx render scene.py\nmanimgx preview scene.py\nmanimgx inspect scene.py\nmanimgx present scene.py",
+ language="bash",
+ background="window",
+ ).scale(1.2)
+ self.play(m.FadeIn(commands))
+ self.wait()
+```
+
+The `manimgx` command makes the video of a scene, an MP4 file, next to the scene's file.
+It also plays the scene in a window while you edit it, checks it for problems a viewer would
+see, draws a still, and presents it as slides. The configuration sets the video's size, frame
+rate and background. From Python, a scene renders into a film, which a program can keep,
+play in a window, or write.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:RenderingHero)
+
+ [**Command line**](command-line.md)
+
+ ---
+
+ `manimgx render`, `preview`, `inspect` and `present`, and their options.
+
+- ![](film:ConfigurationHero)
+
+ [**Configuration**](configuration.md)
+
+ ---
+
+ The video's size and frame rate, its background, and the frame's size in units.
+
+- ![](film:FromPythonHero)
+
+ [**From Python**](from-python.md)
+
+ ---
+
+ Render a scene from a program: its film, its frames, its sound and its captions.
+
+</div>
diff --git a/docs/content/reference/scenes/.nav.yml b/docs/content/reference/scenes/.nav.yml
new file mode 100644
index 00000000..2993b148
--- /dev/null
+++ b/docs/content/reference/scenes/.nav.yml
@@ -0,0 +1,5 @@
+title: "Scenes"
+nav:
+ - Overview: index.md
+ - scene.md
+ - ready-made-scenes.md
diff --git a/docs/content/reference/scenes/index.md b/docs/content/reference/scenes/index.md
new file mode 100644
index 00000000..4a5b4f0d
--- /dev/null
+++ b/docs/content/reference/scenes/index.md
@@ -0,0 +1,57 @@
+---
+title: "Scenes"
+description: "A scene is one video: its construct method says what happens, in order, and its time passes only in plays and waits."
+---
+
+# Scenes
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class ScenesHero(m.Scene):
+ def construct(self) -> None:
+ circle = m.Circle(color=m.BLUE, fill_opacity=0.5)
+ words = m.Text("Hello!", font_size=72)
+ self.play(m.Create(circle))
+ self.play(m.FadeOut(circle))
+ self.play(m.Write(words))
+ self.wait()
+```
+
+A scene is one video. Make a class from [Scene][manimgx.Scene], and write what happens in its
+`construct` method: manimgx runs it from top to bottom, and each line adds to the video in
+that order. The class's name is the video's: the scene `Hello` makes `Hello.mp4`.
+
+Time passes only in [play][manimgx.Scene.play] and [wait][manimgx.Scene.wait]. A play starts
+when the one before it ends and lasts as long as its longest animation; a wait holds the
+picture, while updaters keep running. [add][manimgx.Scene.add] shows a mobject at once,
+taking no time.
+
+<div class="grid cards mx-cards" markdown>
+
+- ![](film:ScenesHero)
+
+ [**Scene**](scene.md)
+
+ ---
+
+ What happens and when: plays and waits, what the scene shows, its sections and its film.
+
+- ![](film:ThreeDScenesHero)
+
+ [**3D scenes**](../camera-and-3d/three-d-scenes.md)
+
+ ---
+
+ A scene seen in three dimensions, from a camera that turns around it.
+
+- ![](film:ReadyMadeScenesHero)
+
+ [**Ready-made scenes**](ready-made-scenes.md)
+
+ ---
+
+ Scenes made for vectors, for linear transformations of the plane, and for a zoomed inset.
+
+</div>
diff --git a/docs/content/reference/scenes/ready-made-scenes.md b/docs/content/reference/scenes/ready-made-scenes.md
new file mode 100644
index 00000000..43adca3d
--- /dev/null
+++ b/docs/content/reference/scenes/ready-made-scenes.md
@@ -0,0 +1,38 @@
+---
+title: "Ready-made scenes"
+description: "Scenes made for one kind of video: vectors on a plane, linear transformations of the plane, and a zoomed inset."
+---
+
+# Ready-made scenes
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class ReadyMadeScenesHero(m.LinearTransformationScene):
+ def construct(self) -> None:
+ self.add_vector([1, 2], color=m.YELLOW)
+ self.apply_matrix([[1, 1], [0, 1]])
+ self.wait()
+```
+
+These scenes come with what one kind of video needs. A vector scene draws vectors from the
+origin of a plane, with their labels and their coordinates. A linear transformation scene
+applies a matrix to the plane and to everything on it, in one play. A zoomed scene shows a
+magnified part of the frame, in an inset.
+
+::: manimgx.VectorScene
+ options:
+ heading_level: 2
+
+::: manimgx.LinearTransformationScene
+ options:
+ heading_level: 2
+
+::: manimgx.ZoomedScene
+ options:
+ heading_level: 2
+
+::: manimgx.scene.ZoomedCameraConfig
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/scenes/scene.md b/docs/content/reference/scenes/scene.md
new file mode 100644
index 00000000..57613e6a
--- /dev/null
+++ b/docs/content/reference/scenes/scene.md
@@ -0,0 +1,150 @@
+---
+title: "Scene"
+description: "The scene: its construct method, the plays and waits that pass its time, the mobjects it shows, its sections, and the film it records."
+---
+
+# Scene
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class SceneHero(m.Scene):
+ def construct(self) -> None:
+ square = m.Square(color=m.BLUE, fill_opacity=0.5)
+ self.add(square)
+ self.wait(0.5)
+ self.play(square.animate.shift(2 * m.RIGHT), run_time=1)
+ self.next_section("turn")
+ self.play(square.animate.rotate(m.PI / 4))
+ self.remove(square)
+ self.wait(0.5)
+```
+
+A scene runs its `construct` method once, from top to bottom, to make its video. Nothing in
+`construct` shows until a play or an add puts it in the scene, and the scene's time moves
+only in a play or a wait: each frame of the video shows the scene at its own exact time.
+
+A scene also speaks and plays sounds: see [Sound](../sound/index.md) and
+[Voice](../sound/voice.md).
+
+::: manimgx.Scene
+ options:
+ heading_level: 2
+ members: false
+
+## What happens
+
+::: manimgx.Scene.construct
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.setup
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.tear_down
+ options:
+ heading_level: 3
+
+## Time
+
+::: manimgx.Scene.play
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.wait
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.pause
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.wait_until
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.time
+ options:
+ heading_level: 3
+
+## What it shows
+
+::: manimgx.Scene.add
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.remove
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.clear
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.replace
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.bring_to_front
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.bring_to_back
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.add_foreground_mobjects
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.remove_foreground_mobjects
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.mobjects
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.foreground_mobjects
+ options:
+ heading_level: 3
+
+## The scene's own updaters
+
+::: manimgx.Scene.add_updater
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.remove_updater
+ options:
+ heading_level: 3
+
+## Sections
+
+::: manimgx.Scene.next_section
+ options:
+ heading_level: 3
+
+## Its camera and its film
+
+::: manimgx.Scene.camera
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.frame
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.three_d
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.film
+ options:
+ heading_level: 3
+
+::: manimgx.Scene.num_plays
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/sound/.nav.yml b/docs/content/reference/sound/.nav.yml
new file mode 100644
index 00000000..3ba24626
--- /dev/null
+++ b/docs/content/reference/sound/.nav.yml
@@ -0,0 +1,4 @@
+title: "Sound"
+nav:
+ - Overview: index.md
+ - voice.md
diff --git a/docs/content/reference/sound/index.md b/docs/content/reference/sound/index.md
new file mode 100644
index 00000000..9c0fa577
--- /dev/null
+++ b/docs/content/reference/sound/index.md
@@ -0,0 +1,49 @@
+---
+title: "Sound"
+description: "Sounds from files or from functions of time, changed and placed in the video: with an animation, at any moment, or under the whole video."
+---
+
+# Sound
+
+```python fold title="The film's code"
+import manimgx as m
+import numpy as np
+
+
+class SoundHero(m.Scene):
+ def construct(self) -> None:
+ def tone(t: np.ndarray) -> np.ndarray:
+ return 0.3 * np.sin(2 * np.pi * 440 * t) * np.exp(-3 * t)
+
+ dots = m.VGroup(
+ *[m.Dot(radius=0.25, color=m.YELLOW) for _ in range(4)]
+ ).arrange(buff=1)
+ for dot in dots:
+ self.play(
+ m.FadeIn(dot, scale=2), m.Sound.of(tone, duration=0.5), run_time=0.5
+ )
+ self.wait()
+```
+
+A sound is read from a file (WAV, MP3, AAC, FLAC and the other usual kinds), or made by a
+function of time. manimgx places each sound at its moment in the video, and mixes them into
+one sound track.
+
+Give a sound to `play` with animations, and it starts with them. To start one at any moment,
+add it: the scene goes on while it plays. A sound plays to its end, or until you stop the
+clip that adding it gives back.
+
+A sound's methods make a changed sound: quieter or louder, faded in or out, trimmed, looped,
+faster, panned, or ducked under a voice.
+
+::: manimgx.Sound
+ options:
+ heading_level: 2
+
+::: manimgx.Scene.add_sound
+ options:
+ heading_level: 2
+
+::: manimgx.audio.sound.Clip
+ options:
+ heading_level: 2
diff --git a/docs/content/reference/sound/voice.md b/docs/content/reference/sound/voice.md
new file mode 100644
index 00000000..3cd1fb8d
--- /dev/null
+++ b/docs/content/reference/sound/voice.md
@@ -0,0 +1,132 @@
+---
+title: "Voice"
+description: "A voice that explains: say a line while animations play during its words, choose a voice, read captions, or make a voice of your own."
+---
+
+# Voice
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class VoiceHero(m.Scene):
+ def construct(self) -> None:
+ square = m.MathTex("x^2", font_size=96).shift(2 * m.LEFT)
+ derivative = m.MathTex("2x", font_size=96).shift(2 * m.RIGHT)
+ arrow = m.Arrow(square.get_right(), derivative.get_left(), buff=0.4)
+ script = m.Text(
+ "The derivative of [x squared] is [two x].", font_size=32
+ ).to_edge(m.DOWN)
+ self.add(square, script)
+ self.play(m.Indicate(square))
+ self.play(m.GrowArrow(arrow), m.Write(derivative))
+ self.wait()
+```
+
+[say][manimgx.Scene.say] speaks a line with the scene's voice, and plays animations while it
+speaks. Put the words of each animation in brackets, and give the animations in the same
+order: each starts with the first of its words. The scene waits until the line ends, so
+lines don't overlap; change the words, and the animations follow the new words.
+
+The scene's voice speaks through a text-to-speech service. manimgx keeps what it says in a
+folder named `voice/`, next to the scene's file, so the scene renders again without the
+service, and only a changed line goes to it again. What the voice says becomes the video's
+captions.
+
+::: manimgx.Scene.say
+ options:
+ heading_level: 2
+
+::: manimgx.Scene.speech
+ options:
+ heading_level: 2
+
+::: manimgx.Scene.voice
+ options:
+ heading_level: 2
+
+::: manimgx.Speech
+ options:
+ heading_level: 2
+
+## Voices
+
+The voices manimgx brings are fal.ai's: `m.voices.Fal`, with the model you choose and its
+settings. Your editor shows each model's settings.
+
+::: manimgx.audio.fal.Fal
+ options:
+ heading_level: 3
+
+### Models { #manimgx.audio.fal }
+
+::: manimgx.audio.fal.ElevenV3
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.MiniMax
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.MiniMaxVoice
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.MiniMaxAudio
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.MiniMaxLoudness
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.MiniMaxTimbre
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.MiniMaxPronunciation
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.Gemini
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.Inworld
+ options:
+ heading_level: 4
+
+::: manimgx.audio.fal.Qwen
+ options:
+ heading_level: 4
+
+## Captions
+
+::: manimgx.Scene.add_subcaption
+ options:
+ heading_level: 3
+
+## A voice of your own
+
+A voice is any function from a text to a [Speech][manimgx.Speech]: a sound that knows its
+words, and when each is said. Any text-to-speech service can be one.
+
+::: manimgx.audio.Voice
+ options:
+ heading_level: 3
+
+::: manimgx.audio.Word
+ options:
+ heading_level: 3
+
+::: manimgx.audio.timed
+ options:
+ heading_level: 3
+
+::: manimgx.audio.estimate
+ options:
+ heading_level: 3
+
+::: manimgx.audio.cached
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/updaters/.nav.yml b/docs/content/reference/updaters/.nav.yml
new file mode 100644
index 00000000..07ea5a75
--- /dev/null
+++ b/docs/content/reference/updaters/.nav.yml
@@ -0,0 +1,4 @@
+title: "Updaters"
+nav:
+ - Overview: index.md
+ - value-trackers.md
diff --git a/docs/content/reference/updaters/index.md b/docs/content/reference/updaters/index.md
new file mode 100644
index 00000000..9006b6c0
--- /dev/null
+++ b/docs/content/reference/updaters/index.md
@@ -0,0 +1,126 @@
+---
+title: "Updaters"
+description: "Rules a mobject keeps at every frame: follow another mobject, show a number, redraw itself, or move as time passes."
+---
+
+# Updaters
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+class UpdatersHero(m.Scene):
+ def construct(self) -> None:
+ dot = m.Dot(color=m.YELLOW).shift(3 * m.LEFT)
+ label = m.Text("dot", font_size=36)
+ label.add_updater(lambda mob: mob.next_to(dot, m.UP))
+ trail = m.TracedPath(dot.get_center, stroke_color=m.YELLOW, stroke_width=4)
+ self.add(trail, dot, label)
+ self.play(dot.animate.shift(6 * m.RIGHT), run_time=2)
+ self.play(m.Rotate(dot, m.PI, about_point=m.ORIGIN), run_time=2)
+ self.wait()
+```
+
+An animation changes a mobject for its run time. An updater changes it at every frame, for
+as long as it is attached: it keeps a rule while other things move. A label stays above a
+dot, a number shows where a tracker is, a shape turns as time passes.
+
+An updater is a function: manimgx calls it with the mobject at every frame, in plays and in
+waits alike. A function that also takes `dt` gets the time since it last ran, in seconds,
+for motion that goes on: `lambda mob, dt: mob.rotate(dt)` turns a mobject a radian a
+second.
+
+## Add an updater
+
+::: manimgx.Mobject.add_updater
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.remove_updater
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.clear_updaters
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.get_updaters
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.suspend_updating
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.resume_updating
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.update
+ options:
+ heading_level: 3
+
+::: manimgx.Mobject.always
+ options:
+ heading_level: 3
+
+## How time-based updaters run
+
+manimgx runs a time-based updater at each tick of the simulation clock, 60 times a second
+whatever the frame rate, so that a simulation gives the same result at every frame rate. A
+flow, which does the same however its time is split, runs at every frame instead; a recorder,
+which reads the world, runs after everything else.
+
+::: manimgx.mobject.flow
+ options:
+ heading_level: 3
+
+::: manimgx.mobject.record
+ options:
+ heading_level: 3
+
+## Ready-made updaters
+
+::: manimgx.always_redraw
+ options:
+ heading_level: 3
+
+::: manimgx.always_rotate
+ options:
+ heading_level: 3
+
+::: manimgx.always_shift
+ options:
+ heading_level: 3
+
+::: manimgx.turn_animation_into_updater
+ options:
+ heading_level: 3
+
+::: manimgx.cycle_animation
+ options:
+ heading_level: 3
+
+## Updaters as animations
+
+::: manimgx.UpdateFromFunc
+ options:
+ heading_level: 3
+
+::: manimgx.UpdateFromAlphaFunc
+ options:
+ heading_level: 3
+
+::: manimgx.MaintainPositionRelativeTo
+ options:
+ heading_level: 3
+
+## Trails and outlines
+
+::: manimgx.TracedPath
+ options:
+ heading_level: 3
+
+::: manimgx.AnimatedBoundary
+ options:
+ heading_level: 3
diff --git a/docs/content/reference/updaters/value-trackers.md b/docs/content/reference/updaters/value-trackers.md
new file mode 100644
index 00000000..b2ab010a
--- /dev/null
+++ b/docs/content/reference/updaters/value-trackers.md
@@ -0,0 +1,43 @@
+---
+title: "Value trackers"
+description: "A number you animate: it shows nothing, and updaters read it, so one animation can move many mobjects."
+---
+
+# Value trackers
+
+```python fold title="The film's code"
+import manimgx as m
+
+
+def curve(x: float) -> float:
+ return x**2 / 4
+
+
+class ValueTrackersHero(m.Scene):
+ def construct(self) -> None:
+ axes = m.Axes(x_range=[0, 5, 1], y_range=[0, 7, 1], x_length=8, y_length=5)
+ graph = axes.plot(curve, color=m.BLUE)
+ x = m.ValueTracker(1)
+ dot = m.always_redraw(
+ lambda: m.Dot(axes.c2p(x.get_value(), curve(x.get_value())), color=m.YELLOW)
+ )
+ number = m.always_redraw(
+ lambda: m.DecimalNumber(x.get_value()).next_to(dot, m.UL)
+ )
+ self.add(axes, graph, dot, number)
+ self.play(x.animate.set_value(4.5), run_time=3)
+ self.wait()
+```
+
+A value tracker holds a number and shows nothing. Animate its number with
+`tracker.animate.set_value(10)`; read it with `tracker.get_value()` in an updater, or in a
+function that [always_redraw][manimgx.always_redraw] calls. One animation of a tracker then
+moves every mobject that reads it.
+
+::: manimgx.ValueTracker
+ options:
+ heading_level: 2
+
+::: manimgx.ComplexValueTracker
+ options:
+ heading_level: 2
diff --git a/docs/deprecated.py b/docs/deprecated.py
index b413c71e..63711bd3 100644
--- a/docs/deprecated.py
+++ b/docs/deprecated.py
@@ -43,7 +43,9 @@ def deprecated(obj: griffe.Object) -> bool:
def getter_decorators(prop: griffe.Attribute) -> list[str]:
"""The names of a property's getter's decorators, as its module writes them."""
- if prop.filepath is None or isinstance(prop.filepath, list):
+ if prop.lineno is None or prop.filepath is None or isinstance(prop.filepath, list):
+ # A native descriptor has no Python definition to inspect. Its module may
+ # name a shared library, which is not source code.
return []
for node in ast.walk(tree(Path(prop.filepath))):
if isinstance(node, ast.FunctionDef) and (node.name, node.lineno) == (
diff --git a/docs/templates/python/material/attribute.html.jinja b/docs/templates/python/material/attribute.html.jinja
index d562d3fa..7f21b2e6 100644
--- a/docs/templates/python/material/attribute.html.jinja
+++ b/docs/templates/python/material/attribute.html.jinja
@@ -11,6 +11,7 @@
{% extends "_base/attribute.html.jinja" %}
{% block heading scoped %}
+ {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
{%- if attribute.parent is not none and attribute.parent.is_class -%}
<span class="doc doc-object-name doc-attribute-name">{{ attribute.name }}</span>
{%- else -%}
diff --git a/docs/templates/python/material/class.html.jinja b/docs/templates/python/material/class.html.jinja
index b1a16f37..8c5ad703 100644
--- a/docs/templates/python/material/class.html.jinja
+++ b/docs/templates/python/material/class.html.jinja
@@ -14,7 +14,7 @@
5. its source, one click away;
6. its members, as the page asks for them.
- With the option `members_only: true`, only the members are shown: a base the package doesn't
+ With the option `extra: {members_only: true}`, only the members are shown: a base the package doesn't
export, shown for what its subclasses share (`GenericGraph`'s, under Graph and DiGraph).
A TypedDict (a vocabulary of keyword options, as `Style`) is shown as its docstring, then
diff --git a/docs/zensical.toml b/docs/zensical.toml
index 528a7b3d..5f49c133 100644
--- a/docs/zensical.toml
+++ b/docs/zensical.toml
@@ -1,7 +1,7 @@
# The docs site: https://zensical.org/docs/setup/basics/
# Build it with `just build-docs` (renders the examples and writes the reference first) into
-# site/, preview it with `just serve-docs`. Its paths are this folder's. Its navigation is its
-# folders': the `.nav.yml` files (awesome-nav).
+# docs/site/, preview it with `just serve-docs`. Its paths are this folder's. Its navigation is
+# its folders': the `.nav.yml` files (awesome-nav).
[project]
site_name = "ManimGX"
@@ -14,15 +14,9 @@ repo_name = "academa-labs/manimgx"
docs_dir = "content"
site_dir = "site"
watch = ["templates"]
-extra_css = [
- "stylesheets/manimgx.css",
- "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css",
-]
-extra_javascript = [
- "https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js",
- "https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js",
- "javascripts/manimgx.js",
-]
+extra_css = ["stylesheets/manimgx.css"]
+# manimgx.js loads KaTeX only when a page has mathematics.
+extra_javascript = ["javascripts/manimgx.js"]
[project.theme]
custom_dir = "overrides"
@@ -153,10 +147,11 @@ manimgx is a self-contained animation engine for AI agents: it makes mathematica
videos from Python scenes. Scenes use the API of Manim Community Edition, and manimgx
annotates all of it with types, so a type checker finds errors before a render. A Rust core
draws each frame on the GPU, typesets text and LaTeX mathematics with Typst, and encodes the
-video and its sound to MP4. The engine calculates each frame at its exact time, so a scene
-is the same at all frame rates. A check command runs a scene without video, prints its
-timeline and layout problems, for example text over other text, and writes a storyboard. In
-a web browser, Pyodide runs the same scenes in a Web Worker, and a WebAssembly build of the
+video and its sound to MP4. Animations are evaluated at each frame's time, and time-based
+simulations use a fixed clock independent of the output frame rate. Per-frame callbacks
+should derive state from time or other objects rather than count frames. The inspect
+command runs a scene without video, prints its timeline and layout problems, for example text
+over other text, and writes a storyboard. In a web browser, Pyodide runs the same scenes in a Web Worker, and a WebAssembly build of the
core draws them with WebGPU.
These are instructions for an AI agent asked to make a video with manimgx. Follow them in order.
@@ -196,15 +191,15 @@ class SquareToCircle(m.Scene):
- Time passes only in `self.play(...)` (1 s unless `run_time=`) and `self.wait(seconds)`; `self.add(...)` shows a mobject without animating it.
- The frame is 14.2 × 8 units centred on the origin: keep everything within x ∈ [-7, 7], y ∈ [-4, 4].
-## 3. Check, then render
+## 3. Inspect, then render
```sh
-manimgx check scene.py # the timeline and layout problems, no video; exit 1 if there are problems
+manimgx inspect scene.py # storyboard, timeline and 2D layout checks; exit 1 for problems
manimgx render scene.py # writes SquareToCircle.mp4 beside scene.py and prints its path
```
-- `check` lists each play with its line of code, then the problems a viewer would see: text the frame cuts off, texts that overlap, lines through a text, text too small to read. Fix them and check again. It also writes `<Scene>.storyboard.png`, the frame at the end of each play with problems outlined: look at it if you can view images.
-- `manimgx still scene.py -t 1.5,end` draws the frames at 1.5 s and at the end into `<Scene>.png`.
+- `inspect` samples play and wait endings. It lists each play with its line of code, reports 2D layout problems, and writes `<Scene>.storyboard.png` with problems outlined and numbered. Look at the pictures if you can view images. Fix problems and inspect again. 3D scenes get storyboards and timelines; layout checks are skipped.
+- `manimgx inspect scene.py -t 1.5,end` inspects the frames at 1.5 s and at the end instead. Repeat `-t` or separate times with commas; `-o detail.png` names the output. Pictures are chronological, six per sheet; more go to `…-2.png`, and so on. Without `end`, inspection stops after the last requested frame's play. Only sampled moments are checked.
- `render` makes 1920×1080 at 60 fps; `-r 1280x720 --fps 30` is quicker for drafts. A file with several scenes needs the scene's name: `manimgx render scene.py MyScene`.
- An error prints the scene's line that failed and, for a wrong name, a hint (`ShowCreation is Create in manimgx`).
- `no GPU adapter` means the command ran in a sandbox that hides the GPU: run it outside the sandbox (ask the user if your tool needs approval).
@@ -272,8 +267,8 @@ show_root_heading = true
show_root_toc_entry = false
show_signature_annotations = false
show_source = true
-show_symbol_type_heading = false
-show_symbol_type_toc = false
+show_symbol_type_heading = true
+show_symbol_type_toc = true
signature_crossrefs = true
unwrap_annotated = true
diff --git a/tests/docs/test_deprecated.py b/tests/docs/test_deprecated.py
index 8f976cf0..420977c3 100644
--- a/tests/docs/test_deprecated.py
+++ b/tests/docs/test_deprecated.py
@@ -115,3 +115,16 @@ def test_what_to_use_instead_stays(tmp_path: Path) -> None:
assert "Zoomed" in names["group"] & names["shapes"]
# an assignment isn't deprecated, to ty or here: the decorator marks a definition
assert "squash" in names["group"]
+
+
+def test_native_properties_have_no_python_getter_to_parse(tmp_path: Path) -> None:
+ pytest.importorskip("griffe")
+ import griffe
+ from docs import deprecated
+
+ library = tmp_path / "_engine.pyd"
+ library.write_bytes(b"\x00\xffnative code")
+ module = griffe.Module("_engine", filepath=library)
+ prop = griffe.Attribute("frames", parent=module)
+ prop.labels.add("property")
+ assert not deprecated.deprecated(prop)
diff --git a/tests/docs/test_hidden.py b/tests/docs/test_hidden.py
index 017a2b45..cea5032e 100644
--- a/tests/docs/test_hidden.py
+++ b/tests/docs/test_hidden.py
@@ -4,12 +4,11 @@ docstrings' nor the example films' (`examples/`, which the Gallery shows). ty ch
not checked."""
import ast
-import subprocess
-import sys
from functools import cache
from pathlib import Path
import pytest
+from tests.typecheck import check
ROOT = Path(__file__).parents[2]
@@ -49,29 +48,42 @@ def test_no_example_uses_a_hidden_name(tmp_path: Path) -> None:
f"# examples/{film.name}\n{film.read_text(encoding='utf-8')}",
encoding="utf-8",
)
- ty = Path(sys.executable).parent / "ty"
- done = subprocess.run(
- [
- str(ty),
- "check",
- "--python",
- sys.prefix,
- "--output-format",
- "concise",
- "--error",
- "deprecated",
- str(tmp_path),
- ],
- capture_output=True,
- text=True,
- check=False,
- )
+ assert_no_hidden_names(sorted(tmp_path.glob("*.py")))
+
+
+def assert_no_hidden_names(files: list[Path]) -> None:
+ """Check explicit files, including examples outside the project's include paths."""
uses = []
- for line in done.stdout.splitlines():
- if "[deprecated]" in line:
- file, number = line.split(":")[:2]
- source = (tmp_path / Path(file).name).read_text(encoding="utf-8")
+ for path, number, _, message in check(files, ("--error", "deprecated")):
+ if message.startswith("error[deprecated]"):
+ source = path.read_text(encoding="utf-8")
uses.append(
- f"{source.splitlines()[0][2:]} (+{number}): {line.split('] ', 1)[1]}"
+ f"{source.splitlines()[0][2:]} (+{number}): {message.split('] ', 1)[1]}"
)
assert not uses, "examples that use a hidden name:\n" + "\n".join(uses)
+
+
+def test_hidden_names_are_checked_outside_project_include_paths(tmp_path: Path) -> None:
+ example = tmp_path / "example.py"
+ example.write_text(
+ "# example on a docs page\n"
+ "from typing_extensions import deprecated\n"
+ '@deprecated("not taught")\n'
+ "def hidden() -> None: pass\n"
+ "hidden()\n",
+ encoding="utf-8",
+ )
+ with pytest.raises(AssertionError, match=r"example on a docs page.*not taught"):
+ assert_no_hidden_names([example])
+
+
+def test_hidden_name_check_does_not_accept_checker_failure(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ example = tmp_path / "example.py"
+ example.write_text("# example on a docs page\nx = 1\n", encoding="utf-8")
+ config = tmp_path / "ty.toml"
+ config.write_text("not valid toml\n", encoding="utf-8")
+ monkeypatch.setenv("TY_CONFIG_FILE", str(config))
+ with pytest.raises(RuntimeError, match=r"ty failed \(2\)"):
+ assert_no_hidden_names([example])
diff --git a/tests/docs/test_llms.py b/tests/docs/test_llms.py
index ec558b3f..ec86e012 100644
--- a/tests/docs/test_llms.py
+++ b/tests/docs/test_llms.py
@@ -9,6 +9,7 @@ from fnmatch import fnmatchcase
from pathlib import Path
import manimgx as m
+from manimgx.cli import app
CONFIG = Path(__file__).parents[2] / "docs" / "zensical.toml"
LLMSTXT = tomllib.loads(CONFIG.read_text(encoding="utf-8"))["project"]["plugins"][
@@ -44,6 +45,16 @@ def test_its_names_exist() -> None:
assert hasattr(m.VMobject, name), f".{name}"
+def test_its_commands_exist() -> None:
+ commands = {
+ c.name or getattr(c.callback, "__name__", "") for c in app.registered_commands
+ }
+ shell = re.findall(r"^```sh\n(.*?)^```", PRIMER, re.MULTILINE | re.DOTALL)
+ inline = re.findall(r"`([^`\n]+)`", PRIMER)
+ for name in re.findall(r"\bmanimgx ([a-z][\w-]*)", "\n".join(shell + inline)):
+ assert name in commands, name
+
+
def test_every_page_has_its_markdown() -> None:
content = CONFIG.parent / "content"
patterns: list[str] = [
diff --git a/tests/docs/test_reference.py b/tests/docs/test_reference.py
index 5248408e..e4d12014 100644
--- a/tests/docs/test_reference.py
+++ b/tests/docs/test_reference.py
@@ -10,13 +10,17 @@ Not what is `@deprecated` (`docs/deprecated.py` takes it out as griffe loads the
deprecated class stays in its module, for the classes made from it, but leaves the reference
with its members, what those classes inherit from it among them. Nor what is listed in
`UNDOCUMENTED`: what can't carry the decorator (an attribute, a constant, a type alias) and no
-scene needs.
+scene needs. And keywords a page shows (a TypedDict, such as `Style`) are shown whole: every
+key, the ones its bases give it too.
"""
import re
+import tomllib
+from dataclasses import fields
from pathlib import Path
import pytest
+import yaml
griffe = pytest.importorskip("griffe") # the docs group's
@@ -27,6 +31,30 @@ CARDS = re.compile(
r'<div class="grid cards mx-cards" markdown>\n(.*?)\n</div>', re.DOTALL
)
+
+def test_reference_options_are_accepted_by_the_installed_handler() -> None:
+ handler = pytest.importorskip("mkdocstrings_handlers.python")
+ config = tomllib.loads((ROOT / "docs/zensical.toml").read_text(encoding="utf-8"))
+ defaults = config["project"]["plugins"]["mkdocstrings"]["handlers"]["python"][
+ "options"
+ ]
+ accepted = {field.name for field in fields(handler.PythonOptions)}
+ handler.PythonOptions.from_data(**defaults)
+ for page in sorted(PAGES.rglob("*.md")):
+ for directive in DIRECTIVE.finditer(page.read_text(encoding="utf-8")):
+ local = yaml.safe_load(directive[2]) or {}
+ options = defaults | local.get("options", {})
+ # With optional Pydantic installed the handler silently drops unknown keys;
+ # the docs-only environment rejects them. Both must receive the same schema.
+ assert not (unknown := options.keys() - accepted), (
+ f"{page.relative_to(PAGES)}: {directive[1]}: unknown options {unknown}"
+ )
+ try:
+ handler.PythonOptions.from_data(**options)
+ except (TypeError, ValueError) as error:
+ pytest.fail(f"{page.relative_to(PAGES)}: {directive[1]}: {error}")
+
+
# What the package documents for its own developers, and the reference leaves out
UNDOCUMENTED = {
# a mobject's state, which its methods and the style keywords read and set
@@ -188,21 +216,26 @@ def shown(package: "griffe.Module") -> dict[str, list[str]]:
continue
options = match[2]
listed = re.search(r"(?<!inherited_)members:\s*(false|\[.*?\])", options)
- own = {
- name: target
- for name, member in obj.members.items()
- if not name.startswith("_")
- and (target := real(member)) is not None
- and documented(target)
- }
+ inherited = re.search(r"inherited_members:\s*(true|\[.*?\])", options)
+ # `inherited_members: true` makes every inherited member one to pick
+ own = (
+ members(obj, set())
+ if inherited and inherited[1] == "true"
+ else {
+ name: target
+ for name, member in obj.members.items()
+ if not name.startswith("_")
+ and (target := real(member)) is not None
+ and documented(target)
+ }
+ )
if listed is None:
chosen = own
elif listed[1] == "false":
chosen = {}
else:
chosen = {n: own[n] for n in re.findall(r"\w+", listed[1]) if n in own}
- inherited = re.search(r"inherited_members:\s*(\[.*?\])", options)
- if inherited:
+ if inherited and inherited[1] != "true":
every = members(obj, set())
chosen |= {n: every[n] for n in re.findall(r"\w+", inherited[1])}
for member in chosen.values():
@@ -273,6 +306,27 @@ def test_nothing_is_shown_twice(package: "griffe.Module") -> None:
assert not twice, f"shown on more than one page, or twice on one: {twice}"
+def keywords(cls: "griffe.Class") -> bool:
+ """Whether a class is a TypedDict: keywords, which a signature unpacks."""
+ return any(
+ "TypedDict" in str(base) for owner in [cls, *cls.mro()] for base in owner.bases
+ )
+
+
+def test_keywords_shown_show_every_key(package: "griffe.Module") -> None:
+ """A page that shows keywords shows each of their keys: there, or with other keywords
+ (`TippedBase`'s style keys are `Style`'s)."""
+ seen = shown(package)
+ missing = sorted(
+ f"{path}.{name}"
+ for path in seen
+ if isinstance(cls := resolve(package, path), griffe.Class) and keywords(cls)
+ for name, key in members(cls, set()).items()
+ if key.path not in seen
+ )
+ assert not missing, f"keys not shown: {missing}"
+
+
def test_undocumented_names_exist(package: "griffe.Module") -> None:
need, _ = required(package)
labels = set(need.values())
@@ -309,3 +363,41 @@ def test_nothing_deprecated_is_shown(package: "griffe.Module") -> None:
if (obj := resolve(package, path)) is not None and deprecated(obj)
)
assert not hidden, f"deprecated, and shown: {hidden}"
+
+
+def test_symbol_badges_in_headings_and_toc() -> None:
+ """The site's settings and custom templates keep Zensical's symbol badges."""
+ markdown = pytest.importorskip("markdown")
+ python = pytest.importorskip("mkdocstrings_handlers.python")
+ docs = ROOT / "docs"
+ config = tomllib.loads((docs / "zensical.toml").read_text(encoding="utf-8"))[
+ "project"
+ ]["plugins"]["mkdocstrings"]
+ handler = python.PythonHandler(
+ config=python.PythonConfig.from_data(**config["handlers"]["python"]),
+ base_dir=docs,
+ theme="material",
+ custom_templates=str(docs / config["custom_templates"]),
+ mdx=["toc"],
+ mdx_config={},
+ )
+ handler._update_env(markdown.Markdown(extensions=["toc"]))
+ options = handler.get_options({"members": False})
+ try:
+ for path, symbol in [
+ ("manimgx.Scene", "class"),
+ ("manimgx.Scene.play", "method"),
+ ("manimgx.smooth", "function"),
+ ("manimgx.Scene.time", "attribute"),
+ ("manimgx.UP", "attribute"),
+ ("manimgx.constants", "module"),
+ ]:
+ html = handler.render(handler.collect(path, options), options)
+ assert f'doc-symbol-heading doc-symbol-{symbol}"' in html, path
+ (heading,) = handler.get_headings()
+ assert (
+ f'doc-symbol-toc doc-symbol-{symbol}"'
+ in heading.attrib["data-toc-label"]
+ ), path
+ finally:
+ handler.teardown()