Custom "Example reference"-blocks for examples with manim directive (#607)

* add seealso options to manim directive

* illustrate use of seealso_classes

* remove unneeded import

* rename: seealso -> ref

* custom styling

* change to ref_classes in example

Author: behackl

docs/source/_static/custom.css

@@ -28,3 +28,8 @@ img {
     padding: 14px 0 14px 20px;
     margin: 20px 0;
 }
+
+div.example-reference {
+    background-color: #dff0d8;
+    border: 1px solid #3c763d;
+}

docs/source/examples/advanced_projects.rst

@@ -2,7 +2,7 @@ Advanced Projects
 =================================
 
 .. manim:: OpeningManimExample
-    :quality: low
+    :ref_classes: Tex MathTex NumberPlane
 
     class OpeningManimExample(Scene):
         def construct(self):
@@ -245,7 +245,7 @@ Advanced Projects
 .. manim:: ExampleSineCurve
 
     class ExampleSineCurve(Scene):
-        # contributed by heejin_park, https://infograph.tistory.com/230 
+        # contributed by heejin_park, https://infograph.tistory.com/230
         def construct(self):
             self.show_axis()
             self.show_circle()

docs/source/manim_directive.py

@@ -21,6 +21,7 @@ def construct(self):
 render scenes that are defined within doctests, for example::
 
     .. manim:: DirectiveDoctestExample
+        :ref_classes: Dot
 
         >>> dot = Dot(color=RED)
         >>> dot.color
@@ -58,19 +59,44 @@ def construct(self):
         an image representing the last frame of the scene will
         be rendered and displayed, instead of a video.
 
+    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 and methods, separated by spaces,
+        that is rendered in a reference block after the source code.
+
 """
 from docutils.parsers.rst import directives, Directive
-from docutils.parsers.rst.directives.images import Image
 
 import jinja2
 import os
 from os.path import relpath
+from typing import List
 
 import shutil
 
 classnamedict = {}
 
 
+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 ManimDirective(Directive):
     r"""The manim directive, rendering videos while building
     the documentation.
@@ -87,6 +113,8 @@ class ManimDirective(Directive):
         ),
         "save_as_gif": bool,
         "save_last_frame": bool,
+        "ref_classes": lambda arg: process_name_list(arg, "class"),
+        "ref_functions": lambda arg: process_name_list(arg, "func"),
     }
     final_argument_whitespace = True
 
@@ -105,6 +133,17 @@ def run(self):
         save_as_gif = "save_as_gif" in self.options
         save_last_frame = "save_last_frame" in self.options
         assert not (save_as_gif and save_last_frame)
+        if "ref_classes" in self.options or "ref_functions" in self.options:
+            ref_classes = self.options.get("ref_classes", [])
+            ref_functions = self.options.get("ref_functions", [])
+            ref_content = ref_classes + ref_functions
+            ref_block = f"""
+.. admonition:: Example References
+    :class: example-reference
+
+    {' '.join(ref_content)}"""
+        else:
+            ref_block = ""
 
         frame_rate = 30
         pixel_height = 480
@@ -218,6 +257,7 @@ def run(self):
             save_last_frame=save_last_frame,
             save_as_gif=save_as_gif,
             source_block=source_block,
+            ref_block=ref_block,
         )
         state_machine.insert_input(
             rendered_template.split("\n"), source=document.attributes["source"]
@@ -245,6 +285,7 @@ def setup(app):
     <div class="manim-example">
 
 {{ source_block }}
+{{ ref_block }}
 {% endif %}
 
 {% if not (save_as_gif or save_last_frame) %}