mirror of
https://github.com/jeertmans/manim-slides.git
synced 2025-05-20 03:57:38 +08:00
fb02764bb7
* feat(lib): add Jupyter magic And also use the same logger level as manim (by default) * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix(lib): remove deleted module * chore(lib): fix typing issues * chore(docs): document magic * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix(ci): install kernel * fix(ci): spawning is not necessary (and fails) * chore(ci): add ipykernel --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
427 lines
12 KiB
Python
427 lines
12 KiB
Python
# type: ignore
|
|
r"""
|
|
A directive for including Manim slides in a Sphinx document
|
|
===========================================================
|
|
|
|
.. warning::
|
|
|
|
This Sphinx extension requires Manim to be installed,
|
|
and won't probably work on ManimGL examples.
|
|
|
|
.. note::
|
|
|
|
The current implementation is highly inspired from Manim's own
|
|
sphinx directive, from v0.17.3.
|
|
|
|
When rendering the HTML documentation, the ``.. manim-slides::``
|
|
directive implemented here allows to include rendered videos.
|
|
|
|
This directive requires three additional dependencies:
|
|
``manim``, ``docutils`` and ``jinja2``. The last two are usually bundled
|
|
with Sphinx.
|
|
You can install them manually, or with the extra keyword:
|
|
|
|
pip install manim-slides[sphinx-directive]
|
|
|
|
Note that you will still need to install Manim's platform-specific dependencies,
|
|
see
|
|
`their installation page <https://docs.manim.community/en/stable/installation.html>`_.
|
|
|
|
Usage
|
|
-----
|
|
|
|
First, you must include the directive in the Sphinx configuration file:
|
|
|
|
.. code-block:: python
|
|
:caption: Sphinx configuration file (usually :code:`docs/source/conf.py`).
|
|
:emphasize-lines: 3
|
|
|
|
extensions = [
|
|
# ...
|
|
"manim_slides.docs.manim_slides_directive",
|
|
]
|
|
|
|
Its basic usage that allows processing **inline content**
|
|
looks as follows::
|
|
|
|
.. manim-slides:: MySlide
|
|
from manim import *
|
|
from manim_slides import Slide
|
|
|
|
class MySlide(Slide):
|
|
def construct(self):
|
|
...
|
|
|
|
It is required to pass the name of the class representing the
|
|
scene to be rendered to the directive.
|
|
|
|
As a second application, the directive can also be used to
|
|
render scenes that are defined within doctests, for example::
|
|
|
|
.. manim-slides:: DirectiveDoctestExample
|
|
:ref_classes: Dot
|
|
|
|
>>> from manim import Create, Dot, RED
|
|
>>> from manim_slides import Slide
|
|
>>> dot = Dot(color=RED)
|
|
>>> dot.color
|
|
<Color #fc6255>
|
|
>>> class DirectiveDoctestExample(Slide):
|
|
... def construct(self):
|
|
... self.play(Create(dot))
|
|
|
|
Options
|
|
-------
|
|
|
|
Options can be passed as follows::
|
|
|
|
.. manim-slides:: <Class name>
|
|
:<option name>: <value>
|
|
|
|
The following configuration options are supported by the
|
|
directive:
|
|
|
|
hide_source
|
|
If this flag is present without argument,
|
|
the source code is not displayed above the rendered video.
|
|
|
|
quality : {'low', 'medium', 'high', 'fourk'}
|
|
Controls render quality of the video, in analogy to
|
|
the corresponding command line flags.
|
|
|
|
ref_classes
|
|
A list of classes, separated by spaces, that is
|
|
rendered in a reference block after the source code.
|
|
|
|
ref_functions
|
|
A list of functions, separated by spaces,
|
|
that is rendered in a reference block after the source code.
|
|
|
|
ref_methods
|
|
A list of methods, separated by spaces,
|
|
that is rendered in a reference block after the source code.
|
|
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import csv
|
|
import itertools as it
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
from timeit import timeit
|
|
|
|
import jinja2
|
|
from docutils import nodes
|
|
from docutils.parsers.rst import Directive, directives
|
|
from docutils.statemachine import StringList
|
|
from manim import QUALITIES
|
|
|
|
from ..convert import RevealJS
|
|
from ..present import get_scenes_presentation_config
|
|
|
|
classnamedict = {}
|
|
|
|
|
|
class SkipManimNode(nodes.Admonition, nodes.Element):
|
|
"""Auxiliary node class that is used when the ``skip-manim-slides`` tag is
|
|
present or ``.pot`` files are being built.
|
|
|
|
Skips rendering the manim-slides directive and outputs a placeholder instead.
|
|
"""
|
|
|
|
pass
|
|
|
|
|
|
def visit(self, node, name=""):
|
|
self.visit_admonition(node, name)
|
|
if not isinstance(node[0], nodes.title):
|
|
node.insert(0, nodes.title("skip-manim-slides", "Example Placeholder"))
|
|
|
|
|
|
def depart(self, node):
|
|
self.depart_admonition(node)
|
|
|
|
|
|
def process_name_list(option_input: str, reference_type: str) -> list[str]:
|
|
r"""Reformats a string of space separated class names
|
|
as a list of strings containing valid Sphinx references.
|
|
|
|
Tests
|
|
-----
|
|
|
|
::
|
|
|
|
>>> process_name_list("Tex TexTemplate", "class")
|
|
[':class:`~.Tex`', ':class:`~.TexTemplate`']
|
|
>>> process_name_list("Scene.play Mobject.rotate", "func")
|
|
[':func:`~.Scene.play`', ':func:`~.Mobject.rotate`']
|
|
"""
|
|
return [f":{reference_type}:`~.{name}`" for name in option_input.split()]
|
|
|
|
|
|
class ManimSlidesDirective(Directive):
|
|
r"""The manim-slides directive, rendering videos while building
|
|
the documentation.
|
|
|
|
See the module docstring for documentation.
|
|
"""
|
|
has_content = True
|
|
required_arguments = 1
|
|
optional_arguments = 0
|
|
option_spec = {
|
|
"hide_source": bool,
|
|
"quality": lambda arg: directives.choice(
|
|
arg,
|
|
("low", "medium", "high", "fourk"),
|
|
),
|
|
"ref_modules": lambda arg: process_name_list(arg, "mod"),
|
|
"ref_classes": lambda arg: process_name_list(arg, "class"),
|
|
"ref_functions": lambda arg: process_name_list(arg, "func"),
|
|
"ref_methods": lambda arg: process_name_list(arg, "meth"),
|
|
}
|
|
final_argument_whitespace = True
|
|
|
|
def run(self):
|
|
# Rendering is skipped if the tag skip-manim is present,
|
|
# or if we are making the pot-files
|
|
should_skip = (
|
|
"skip-manim-slides"
|
|
in self.state.document.settings.env.app.builder.tags.tags
|
|
or self.state.document.settings.env.app.builder.name == "gettext"
|
|
)
|
|
if should_skip:
|
|
node = SkipManimNode()
|
|
self.state.nested_parse(
|
|
StringList(
|
|
[
|
|
f"Placeholder block for ``{self.arguments[0]}``.",
|
|
"",
|
|
".. code-block:: python",
|
|
"",
|
|
]
|
|
+ [" " + line for line in self.content]
|
|
),
|
|
self.content_offset,
|
|
node,
|
|
)
|
|
return [node]
|
|
|
|
from manim import config, tempconfig
|
|
|
|
global classnamedict
|
|
|
|
clsname = self.arguments[0]
|
|
if clsname not in classnamedict:
|
|
classnamedict[clsname] = 1
|
|
else:
|
|
classnamedict[clsname] += 1
|
|
|
|
hide_source = "hide_source" in self.options
|
|
|
|
ref_content = (
|
|
self.options.get("ref_modules", [])
|
|
+ self.options.get("ref_classes", [])
|
|
+ self.options.get("ref_functions", [])
|
|
+ self.options.get("ref_methods", [])
|
|
)
|
|
if ref_content:
|
|
ref_block = "References: " + " ".join(ref_content)
|
|
|
|
else:
|
|
ref_block = ""
|
|
|
|
if "quality" in self.options:
|
|
quality = f'{self.options["quality"]}_quality'
|
|
else:
|
|
quality = "example_quality"
|
|
frame_rate = QUALITIES[quality]["frame_rate"]
|
|
pixel_height = QUALITIES[quality]["pixel_height"]
|
|
pixel_width = QUALITIES[quality]["pixel_width"]
|
|
|
|
state_machine = self.state_machine
|
|
document = state_machine.document
|
|
|
|
source_file_name = Path(document.attributes["source"])
|
|
source_rel_name = source_file_name.relative_to(setup.confdir)
|
|
source_rel_dir = source_rel_name.parents[0]
|
|
dest_dir = Path(setup.app.builder.outdir, source_rel_dir).absolute()
|
|
if not dest_dir.exists():
|
|
dest_dir.mkdir(parents=True, exist_ok=True)
|
|
|
|
source_block = [
|
|
".. code-block:: python",
|
|
"",
|
|
*(" " + line for line in self.content),
|
|
]
|
|
source_block = "\n".join(source_block)
|
|
|
|
config.media_dir = (Path(setup.confdir) / "media").absolute()
|
|
config.images_dir = "{media_dir}/images"
|
|
config.video_dir = "{media_dir}/videos/{quality}"
|
|
output_file = f"{clsname}-{classnamedict[clsname]}"
|
|
config.assets_dir = Path("_static")
|
|
config.progress_bar = "none"
|
|
config.verbosity = "WARNING"
|
|
|
|
example_config = {
|
|
"frame_rate": frame_rate,
|
|
"pixel_height": pixel_height,
|
|
"pixel_width": pixel_width,
|
|
"output_file": output_file,
|
|
}
|
|
|
|
user_code = self.content
|
|
if user_code[0].startswith(">>> "): # check whether block comes from doctest
|
|
user_code = [
|
|
line[4:] for line in user_code if line.startswith((">>> ", "... "))
|
|
]
|
|
|
|
code = [
|
|
"from manim import *",
|
|
*user_code,
|
|
f"{clsname}().render()",
|
|
]
|
|
|
|
try:
|
|
with tempconfig(example_config):
|
|
run_time = timeit(lambda: exec("\n".join(code), globals()), number=1)
|
|
video_dir = config.get_dir("video_dir")
|
|
except Exception as e:
|
|
raise RuntimeError(f"Error while rendering example {clsname}") from e
|
|
|
|
_write_rendering_stats(
|
|
clsname,
|
|
run_time,
|
|
self.state.document.settings.env.docname,
|
|
)
|
|
|
|
# copy video file to output directory
|
|
filename = f"{output_file}.html"
|
|
filesrc = video_dir / filename
|
|
destfile = Path(dest_dir, filename)
|
|
presentation_configs = get_scenes_presentation_config(
|
|
[clsname], Path("./slides")
|
|
)
|
|
RevealJS(presentation_configs=presentation_configs, controls="true").convert_to(
|
|
destfile
|
|
)
|
|
# shutil.copyfile(filesrc, destfile)
|
|
|
|
print("CLASS NAME:", clsname)
|
|
|
|
rendered_template = jinja2.Template(TEMPLATE).render(
|
|
clsname=clsname,
|
|
clsname_lowercase=clsname.lower(),
|
|
hide_source=hide_source,
|
|
filesrc_rel=Path(filesrc).relative_to(setup.confdir).as_posix(),
|
|
output_file=output_file,
|
|
source_block=source_block,
|
|
ref_block=ref_block,
|
|
)
|
|
state_machine.insert_input(
|
|
rendered_template.split("\n"),
|
|
source=document.attributes["source"],
|
|
)
|
|
|
|
return []
|
|
|
|
|
|
rendering_times_file_path = Path("../rendering_times.csv")
|
|
|
|
|
|
def _write_rendering_stats(scene_name, run_time, file_name):
|
|
with rendering_times_file_path.open("a") as file:
|
|
csv.writer(file).writerow(
|
|
[
|
|
re.sub(r"^(reference\/)|(manim\.)", "", file_name),
|
|
scene_name,
|
|
"%.3f" % run_time,
|
|
],
|
|
)
|
|
|
|
|
|
def _log_rendering_times(*args):
|
|
if rendering_times_file_path.exists():
|
|
with rendering_times_file_path.open() as file:
|
|
data = list(csv.reader(file))
|
|
if len(data) == 0:
|
|
sys.exit()
|
|
|
|
print("\nRendering Summary\n-----------------\n")
|
|
|
|
max_file_length = max(len(row[0]) for row in data)
|
|
for key, group in it.groupby(data, key=lambda row: row[0]):
|
|
key = key.ljust(max_file_length + 1, ".")
|
|
group = list(group)
|
|
if len(group) == 1:
|
|
row = group[0]
|
|
print(f"{key}{row[2].rjust(7, '.')}s {row[1]}")
|
|
continue
|
|
time_sum = sum(float(row[2]) for row in group)
|
|
print(
|
|
f"{key}{f'{time_sum:.3f}'.rjust(7, '.')}s => {len(group)} EXAMPLES",
|
|
)
|
|
for row in group:
|
|
print(f"{' '*(max_file_length)} {row[2].rjust(7)}s {row[1]}")
|
|
print("")
|
|
|
|
|
|
def _delete_rendering_times(*args):
|
|
if rendering_times_file_path.exists():
|
|
rendering_times_file_path.unlink()
|
|
|
|
|
|
def setup(app):
|
|
app.add_node(SkipManimNode, html=(visit, depart))
|
|
|
|
setup.app = app
|
|
setup.config = app.config
|
|
setup.confdir = app.confdir
|
|
|
|
app.add_directive("manim-slides", ManimSlidesDirective)
|
|
|
|
app.connect("builder-inited", _delete_rendering_times)
|
|
app.connect("build-finished", _log_rendering_times)
|
|
|
|
metadata = {"parallel_read_safe": False, "parallel_write_safe": True}
|
|
return metadata
|
|
|
|
|
|
TEMPLATE = r"""
|
|
{% if not hide_source %}
|
|
.. raw:: html
|
|
|
|
<div id="{{ clsname_lowercase }}" class="admonition admonition-manim-example">
|
|
<p class="admonition-title">Example: {{ clsname }} <a class="headerlink" href="#{{ clsname_lowercase }}">¶</a></p>
|
|
|
|
{% endif %}
|
|
|
|
|
|
.. raw:: html
|
|
|
|
|
|
<div style="position:relative;padding-bottom:56.25%;">
|
|
<iframe
|
|
style="width:100%;height:100%;position:absolute;left:0px;top:0px;"
|
|
frameborder="0"
|
|
width="100%"
|
|
height="100%"
|
|
allowfullscreen
|
|
allow="autoplay"
|
|
src="./{{ output_file }}.html">
|
|
</iframe>
|
|
</div>
|
|
|
|
{% if not hide_source %}
|
|
{{ source_block }}
|
|
|
|
{{ ref_block }}
|
|
|
|
.. raw:: html
|
|
|
|
</div>
|
|
|
|
{% endif %}
|
|
"""
|