manim 0.18.0.post0__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/utils/docbuild/autoaliasattr_directive.py

@@ -0,0 +1,234 @@
+"""A directive for documenting type aliases and other module-level attributes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.statemachine import ViewList
+
+from manim.utils.docbuild.module_parsing import parse_module_attributes
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__all__ = ["AliasAttrDocumenter"]
+
+
+ALIAS_DOCS_DICT, DATA_DICT, TYPEVAR_DICT = parse_module_attributes()
+ALIAS_LIST = [
+    alias_name
+    for module_dict in ALIAS_DOCS_DICT.values()
+    for category_dict in module_dict.values()
+    for alias_name in category_dict
+]
+
+
+def smart_replace(base: str, alias: str, substitution: str) -> str:
+    """Auxiliary function for substituting type aliases into a base
+    string, when there are overlaps between the aliases themselves.
+
+    Parameters
+    ----------
+    base
+        The string in which the type aliases will be located and
+        replaced.
+    alias
+        The substring to be substituted.
+    substitution
+        The string which will replace every occurrence of ``alias``.
+
+    Returns
+    -------
+    str
+        The new string after the alias substitution.
+    """
+    occurrences = []
+    len_alias = len(alias)
+    len_base = len(base)
+
+    def condition(char: str) -> bool:
+        return not char.isalnum() and char != "_"
+
+    start = 0
+    i = 0
+    while True:
+        i = base.find(alias, start)
+        if i == -1:
+            break
+        if (i == 0 or condition(base[i - 1])) and (
+            i + len_alias == len_base or condition(base[i + len_alias])
+        ):
+            occurrences.append(i)
+        start = i + len_alias
+
+    for o in occurrences[::-1]:
+        base = base[:o] + substitution + base[o + len_alias :]
+
+    return base
+
+
+def setup(app: Sphinx) -> None:
+    app.add_directive("autoaliasattr", AliasAttrDocumenter)
+
+
+class AliasAttrDocumenter(Directive):
+    """Directive which replaces Sphinx's Autosummary for module-level
+    attributes: instead, it manually crafts a new "Type Aliases"
+    section, where all the module-level attributes which are explicitly
+    annotated as :class:`TypeAlias` are considered as such, for their
+    use all around the Manim docs.
+
+    These type aliases are separated from the "regular" module-level
+    attributes, which get their traditional "Module Attributes"
+    section autogenerated with Sphinx's Autosummary under "Type
+    Aliases".
+
+    See ``docs/source/_templates/autosummary/module.rst`` to watch
+    this directive in action.
+
+    See :func:`~.parse_module_attributes` for more information on how
+    the modules are parsed to obtain the :class:`TypeAlias` information
+    and separate it from the other attributes.
+    """
+
+    objtype = "autoaliasattr"
+    required_arguments = 1
+    has_content = True
+
+    def run(self) -> list[nodes.Element]:
+        module_name = self.arguments[0]
+        # not present in the keys of the DICTs
+        module_name = module_name.removeprefix("manim.")
+        module_alias_dict = ALIAS_DOCS_DICT.get(module_name, None)
+        module_attrs_list = DATA_DICT.get(module_name, None)
+        module_typevars = TYPEVAR_DICT.get(module_name, None)
+
+        content = nodes.container()
+
+        # Add "Type Aliases" section
+        if module_alias_dict is not None:
+            module_alias_section = nodes.section(ids=[f"{module_name}.alias"])
+            content += module_alias_section
+
+            # Use a rubric (title-like), just like in `module.rst`
+            module_alias_section += nodes.rubric(text="Type Aliases")
+
+            # category_name: str
+            # category_dict: AliasCategoryDict = dict[str, AliasInfo]
+            for category_name, category_dict in module_alias_dict.items():
+                category_section = nodes.section(
+                    ids=[category_name.lower().replace(" ", "_")]
+                )
+                module_alias_section += category_section
+                # category_name can be possibly "" for uncategorized aliases
+                if category_name:
+                    category_section += nodes.title(text=category_name)
+
+                category_alias_container = nodes.container()
+                category_section += category_alias_container
+
+                # alias_name: str
+                # alias_info: AliasInfo = dict[str, str]
+                #   Contains "definition": str
+                #   Can possibly contain "doc": str
+                for alias_name, alias_info in category_dict.items():
+                    # Replace all occurrences of type aliases in the
+                    # definition for automatic cross-referencing!
+                    alias_def = alias_info["definition"]
+                    for A in ALIAS_LIST:
+                        alias_def = smart_replace(alias_def, A, f":class:`~.{A}`")
+
+                    # Using the `.. class::` directive is CRUCIAL, since
+                    # function/method parameters are always annotated via
+                    # classes - therefore Sphinx expects a class
+                    unparsed = ViewList(
+                        [
+                            f".. class:: {alias_name}",
+                            "",
+                            "    .. parsed-literal::",
+                            "",
+                            f"        {alias_def}",
+                            "",
+                        ]
+                    )
+
+                    if "doc" in alias_info:
+                        # Replace all occurrences of type aliases in
+                        # the docs for automatic cross-referencing!
+                        alias_doc = alias_info["doc"]
+                        for A in ALIAS_LIST:
+                            alias_doc = alias_doc.replace(f"`{A}`", f":class:`~.{A}`")
+
+                        # also hyperlink the TypeVars from that module
+                        if module_typevars is not None:
+                            for T in module_typevars:
+                                alias_doc = alias_doc.replace(f"`{T}`", f":class:`{T}`")
+
+                        # Add all the lines with 4 spaces behind, to consider all the
+                        # documentation as a paragraph INSIDE the `.. class::` block
+                        doc_lines = alias_doc.split("\n")
+                        unparsed.extend(ViewList([f"    {line}" for line in doc_lines]))
+
+                    # Parse the reST text into a fresh container
+                    # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+                    alias_container = nodes.container()
+                    self.state.nested_parse(unparsed, 0, alias_container)
+                    category_alias_container += alias_container
+
+        # then add the module TypeVars section
+        if module_typevars is not None:
+            module_typevars_section = nodes.section(ids=[f"{module_name}.typevars"])
+            content += module_typevars_section
+
+            # Use a rubric (title-like), just like in `module.rst`
+            module_typevars_section += nodes.rubric(text="TypeVar's")
+
+            # name: str
+            # definition: TypeVarDict = dict[str, str]
+            for name, definition in module_typevars.items():
+                # Using the `.. class::` directive is CRUCIAL, since
+                # function/method parameters are always annotated via
+                # classes - therefore Sphinx expects a class
+                unparsed = ViewList(
+                    [
+                        f".. class:: {name}",
+                        "",
+                        "    .. parsed-literal::",
+                        "",
+                        f"        {definition}",
+                        "",
+                    ]
+                )
+
+                # Parse the reST text into a fresh container
+                # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+                typevar_container = nodes.container()
+                self.state.nested_parse(unparsed, 0, typevar_container)
+                module_typevars_section += typevar_container
+
+        # Then, add the traditional "Module Attributes" section
+        if module_attrs_list is not None:
+            module_attrs_section = nodes.section(ids=[f"{module_name}.data"])
+            content += module_attrs_section
+
+            # Use the same rubric (title-like) as in `module.rst`
+            module_attrs_section += nodes.rubric(text="Module Attributes")
+            # Let Sphinx Autosummary do its thing as always
+            # Add all the attribute names with 4 spaces behind, so that
+            # they're considered as INSIDE the `.. autosummary::` block
+            unparsed = ViewList(
+                [
+                    ".. autosummary::",
+                    *(f"    {attr}" for attr in module_attrs_list),
+                ]
+            )
+
+            # Parse the reST text into a fresh container
+            # https://www.sphinx-doc.org/en/master/extdev/markupapi.html#parsing-directive-content-as-rest
+            data_container = nodes.container()
+            self.state.nested_parse(unparsed, 0, data_container)
+            module_attrs_section += data_container
+
+        return [content]

manim/utils/docbuild/autocolor_directive.py

@@ -1,13 +1,20 @@
+"""A directive for documenting colors in Manim."""
+
 from __future__ import annotations
 
 import inspect
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
-from sphinx.application import Sphinx
 
 from manim import ManimColor
 
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__all__ = ["ManimColorModuleDocumenter"]
+
 
 def setup(app: Sphinx) -> None:
     app.add_directive("automanimcolormodule", ManimColorModuleDocumenter)
@@ -19,11 +26,11 @@ class ManimColorModuleDocumenter(Directive):
     has_content = True
 
     def add_directive_header(self, sig: str) -> None:
-        super().add_directive_header(sig)
+        # TODO: The Directive class has no method named
+        # add_directive_header.
+        super().add_directive_header(sig)  # type: ignore[misc]
 
-    def run(
-        self,
-    ) -> None:
+    def run(self) -> list[nodes.Element]:
         module_name = self.arguments[0]
         try:
             import importlib
@@ -32,8 +39,8 @@ class ManimColorModuleDocumenter(Directive):
         except ImportError:
             return [
                 nodes.error(
-                    None,
-                    nodes.paragraph(text="Failed to import module '%s'" % module_name),
+                    None,  # type: ignore[arg-type]
+                    nodes.paragraph(text=f"Failed to import module '{module_name}'"),
                 )
             ]
 
@@ -48,13 +55,13 @@ class ManimColorModuleDocumenter(Directive):
 
         # Create header rows for the table
         thead = nodes.thead()
-        row = nodes.row()
+        header_row = nodes.row()
         for _ in range(num_color_cols):
-            col1 = nodes.paragraph(text="Color Name")
-            col2 = nodes.paragraph(text="RGB Hex Code")
-            row += nodes.entry("", col1)
-            row += nodes.entry("", col2)
-        thead += row
+            header_col1 = nodes.paragraph(text="Color Name")
+            header_col2 = nodes.paragraph(text="RGB Hex Code")
+            header_row += nodes.entry("", header_col1)
+            header_row += nodes.entry("", header_col2)
+        thead += header_row
         tgroup += thead
 
         color_elements = []
@@ -64,10 +71,7 @@ class ManimColorModuleDocumenter(Directive):
                 luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
 
                 # Choose the font color based on the background luminance
-                if luminance > 0.5:
-                    font_color = "black"
-                else:
-                    font_color = "white"
+                font_color = "black" if luminance > 0.5 else "white"
 
                 color_elements.append((member_name, member_obj.to_hex(), font_color))
 

manim/utils/docbuild/manim_directive.py

@@ -77,27 +77,40 @@ directive:
         that is rendered in a reference block after the source code.
 
 """
+
 from __future__ import annotations
 
 import csv
 import itertools as it
-import os
 import re
 import shutil
 import sys
 import textwrap
 from pathlib import Path
 from timeit import timeit
+from typing import TYPE_CHECKING, Any, TypedDict
 
 import jinja2
 from docutils import nodes
-from docutils.parsers.rst import Directive, directives  # type: ignore
+from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import StringList
 
 from manim import QUALITIES
 from manim import __version__ as manim_version
 
-classnamedict = {}
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+__all__ = ["ManimDirective"]
+
+
+classnamedict: dict[str, int] = {}
+
+
+class SetupMetadata(TypedDict):
+    parallel_read_safe: bool
+    parallel_write_safe: bool
 
 
 class SkipManimNode(nodes.Admonition, nodes.Element):
@@ -110,14 +123,16 @@ class SkipManimNode(nodes.Admonition, nodes.Element):
     pass
 
 
-def visit(self, node, name=""):
-    self.visit_admonition(node, name)
+def visit(self: SkipManimNode, node: nodes.Element, name: str = "") -> None:
+    # TODO: Parent classes don't have a visit_admonition() method.
+    self.visit_admonition(node, name)  # type: ignore[attr-defined]
     if not isinstance(node[0], nodes.title):
         node.insert(0, nodes.title("skip-manim", "Example Placeholder"))
 
 
-def depart(self, node):
-    self.depart_admonition(node)
+def depart(self: SkipManimNode, node: nodes.Element) -> None:
+    # TODO: Parent classes don't have a depart_admonition() method.
+    self.depart_admonition(node)  # type: ignore[attr-defined]
 
 
 def process_name_list(option_input: str, reference_type: str) -> list[str]:
@@ -143,6 +158,7 @@ class ManimDirective(Directive):
 
     See the module docstring for documentation.
     """
+
     has_content = True
     required_arguments = 1
     optional_arguments = 0
@@ -162,11 +178,11 @@ class ManimDirective(Directive):
     }
     final_argument_whitespace = True
 
-    def run(self):
+    def run(self) -> list[nodes.Element]:
         # Rendering is skipped if the tag skip-manim is present,
         # or if we are making the pot-files
         should_skip = (
-            "skip-manim" in self.state.document.settings.env.app.builder.tags.tags
+            "skip-manim" in self.state.document.settings.env.app.builder.tags
             or self.state.document.settings.env.app.builder.name == "gettext"
         )
         if should_skip:
@@ -217,14 +233,10 @@ class ManimDirective(Directive):
             + self.options.get("ref_functions", [])
             + self.options.get("ref_methods", [])
         )
-        if ref_content:
-            ref_block = "References: " + " ".join(ref_content)
-
-        else:
-            ref_block = ""
+        ref_block = "References: " + " ".join(ref_content) if ref_content else ""
 
         if "quality" in self.options:
-            quality = f'{self.options["quality"]}_quality'
+            quality = f"{self.options['quality']}_quality"
         else:
             quality = "example_quality"
         frame_rate = QUALITIES[quality]["frame_rate"]
@@ -235,13 +247,13 @@ class ManimDirective(Directive):
         document = state_machine.document
 
         source_file_name = Path(document.attributes["source"])
-        source_rel_name = source_file_name.relative_to(setup.confdir)
+        source_rel_name = source_file_name.relative_to(setup.confdir)  # type: ignore[attr-defined]
         source_rel_dir = source_rel_name.parents[0]
-        dest_dir = Path(setup.app.builder.outdir, source_rel_dir).absolute()
+        dest_dir = Path(setup.app.builder.outdir, source_rel_dir).absolute()  # type: ignore[attr-defined]
         if not dest_dir.exists():
             dest_dir.mkdir(parents=True, exist_ok=True)
 
-        source_block = [
+        source_block_in = [
             ".. code-block:: python",
             "",
             "    from manim import *\n",
@@ -254,13 +266,13 @@ class ManimDirective(Directive):
             "",
             "    </pre>",
         ]
-        source_block = "\n".join(source_block)
+        source_block = "\n".join(source_block_in)
 
-        config.media_dir = (Path(setup.confdir) / "media").absolute()
+        config.media_dir = (Path(setup.confdir) / "media").absolute()  # type: ignore[attr-defined,assignment]
         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.assets_dir = Path("_static")  # type: ignore[assignment]
         config.progress_bar = "none"
         config.verbosity = "WARNING"
 
@@ -278,7 +290,7 @@ class ManimDirective(Directive):
         if save_as_gif:
             example_config["format"] = "gif"
 
-        user_code = self.content
+        user_code = list(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((">>> ", "... "))
@@ -322,7 +334,7 @@ class ManimDirective(Directive):
             clsname=clsname,
             clsname_lowercase=clsname.lower(),
             hide_source=hide_source,
-            filesrc_rel=Path(filesrc).relative_to(setup.confdir).as_posix(),
+            filesrc_rel=Path(filesrc).relative_to(setup.confdir).as_posix(),  # type: ignore[attr-defined]
             no_autoplay=no_autoplay,
             output_file=output_file,
             save_last_frame=save_last_frame,
@@ -341,18 +353,18 @@ class ManimDirective(Directive):
 rendering_times_file_path = Path("../rendering_times.csv")
 
 
-def _write_rendering_stats(scene_name, run_time, file_name):
+def _write_rendering_stats(scene_name: str, run_time: float, file_name: str) -> None:
     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,
+                f"{run_time:.3f}",
             ],
         )
 
 
-def _log_rendering_times(*args):
+def _log_rendering_times(*args: tuple[Any]) -> None:
     if rendering_times_file_path.exists():
         with rendering_times_file_path.open() as file:
             data = list(csv.reader(file))
@@ -365,9 +377,9 @@ def _log_rendering_times(*args):
         data = [row for row in data if row]
 
         max_file_length = max(len(row[0]) for row in data)
-        for key, group in it.groupby(data, key=lambda row: row[0]):
+        for key, group_iter in it.groupby(data, key=lambda row: row[0]):
             key = key.ljust(max_file_length + 1, ".")
-            group = list(group)
+            group = list(group_iter)
             if len(group) == 1:
                 row = group[0]
                 print(f"{key}{row[2].rjust(7, '.')}s {row[1]}")
@@ -377,21 +389,21 @@ def _log_rendering_times(*args):
                 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(f"{' ' * max_file_length} {row[2].rjust(7)}s {row[1]}")
         print("")
 
 
-def _delete_rendering_times(*args):
+def _delete_rendering_times(*args: tuple[Any]) -> None:
     if rendering_times_file_path.exists():
         rendering_times_file_path.unlink()
 
 
-def setup(app):
+def setup(app: Sphinx) -> SetupMetadata:
     app.add_node(SkipManimNode, html=(visit, depart))
 
-    setup.app = app
-    setup.config = app.config
-    setup.confdir = app.confdir
+    setup.app = app  # type: ignore[attr-defined]
+    setup.config = app.config  # type: ignore[attr-defined]
+    setup.confdir = app.confdir  # type: ignore[attr-defined]
 
     app.add_directive("manim", ManimDirective)
 
@@ -408,7 +420,10 @@ def setup(app):
         ).strip(),
     )
 
-    metadata = {"parallel_read_safe": False, "parallel_write_safe": True}
+    metadata: SetupMetadata = {
+        "parallel_read_safe": False,
+        "parallel_write_safe": True,
+    }
     return metadata