Manim Slides’ Sphinx directive¶

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.

Usage¶

First, you must include the directive in the Sphinx configuration file:

Sphinx configuration file (usually docs/source/conf.py).¶

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

A third application is to render scenes from another specific file:

.. manim-slides:: file.py:FileExample
    :hide_source:
    :quality: high

Warning

The code will be executed with the current working directory being the same as the one containing the source file. This being said, you should probably not include examples that rely on external files, since relative paths risk to be broken.

Note

If you want to skip rendering the slides (e.g., for testing) you can either set the SKIP_MANIM_SLIDES environ variable (to any value) or pass the skip-manim-slides tag to sphinx:

sphinx-build -t skip-manim-slides <OTHER_SPHINX_OPTIONS>
# or if you use a Makefile
make html O=-tskip-manim-slides

Options¶

Options can be passed as follows:

.. manim-slides:: <file>:<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.

template
A path to the template file to use.

config_options
An unprocessed string of options to pass to manim-slides convert. Options must be separated with a space, and each option must be a key, value pair using an equal sign as a separator.

Unlike for the CLI version, you don’t need to prepend each option with -c.

E.g., pass slide_number=true controls=false.

By default, controls=true is set.

Examples¶

The following code:

.. manim-slides:: MySlide
    :hide_source:
    :config_options: slide_number=true controls=false

    from manim import *
    from manim_slides import Slide

    class MySlide(Slide):
        def construct(self):
            text = Text("Hello")
            self.wipe([], text)

            self.next_slide()
            self.play(text.animate.scale(2))

            self.next_slide()
            self.zoom(text)

Renders as follows:

class ManimSlidesDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

The manim-slides directive, rendering videos while building the documentation.

See the module docstring for documentation.

final_argument_whitespace = True¶: May the final argument contain whitespace?

has_content = True¶: May the directive have content?

option_spec = {'config_options': <function ManimSlidesDirective.<lambda>>, 'hide_source': <class 'bool'>, 'quality': <function ManimSlidesDirective.<lambda>>, 'ref_classes': <function ManimSlidesDirective.<lambda>>, 'ref_functions': <function ManimSlidesDirective.<lambda>>, 'ref_methods': <function ManimSlidesDirective.<lambda>>, 'ref_modules': <function ManimSlidesDirective.<lambda>>, 'template': <function ManimSlidesDirective.<lambda>>}¶: Mapping of option names to validator functions.

optional_arguments = 0¶: Number of optional arguments after the required arguments.

required_arguments = 1¶: Number of required directive arguments.