Added support for Manim type aliases in Sphinx docs + Added new TypeAliases (#3484)

* Updated manim.typing and included TypeAliases in docs.source.conf

* Added Vector2 and reorganized manim_type_aliases

* Fixed __all__ exports for __all__ of manim

* Update manim/cli/render/global_options.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Draft of new typing docs and new autotyping directive

* Changed vertical bars to Unions

* Updated poetry.lock

* Created custom file parser for manim.typing

* Got reST parser going

* Updated autotyping and parsing

* Update parsing

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Added code_block toggle

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Added typings to directives

* Renamed Tuple to tuple in manim.typings

* Added missing docs for type aliases

* Fixed exponent typo in ManimInt

* Hyperlinks to types work - removed Module Attributes section

* Removed Unused Import

Remove ``import re``

* Added freeglut-devel to workflows for Linux

Hopefully (?) fix the GLU import error

* Fix package name

* Add support for Type Aliases section in every module - Renaming of Vector types

* Add/fix docs for directive, parser and others

* Fixed alias typo in module_parsing

* Fix decode/import bugs, fix minor details in docs

* Added missing docs for utils.docbuild and utils.testing

* Sort alphabetically entries in utilities_misc.rst

* Address review comments, add notes about Vector and hyperlinks inside definition blocks

---------

Co-authored-by: MrDiver <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: JasonGrace2282 <[email protected]>

Author: 4 people

.github/workflows/ci.yml

@@ -60,7 +60,7 @@ jobs:
         if: runner.os == 'Linux'
         uses: awalsh128/cache-apt-pkgs-action@latest
         with:
-          packages: python3-opengl libpango1.0-dev xvfb
+          packages: python3-opengl libpango1.0-dev xvfb freeglut3-dev
           version: 1.0
 
       - name: Install Texlive (Linux)

docs/source/_templates/autosummary/module.rst

@@ -4,16 +4,9 @@
 
 .. automodule:: {{ fullname }}
 
-   {% block attributes %}
-   {% if attributes %}
-   .. rubric:: Module Attributes
-
-   .. autosummary::
-   {% for item in attributes %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
+   {# SEE manim.utils.docbuild.autoaliasattr_directive #}
+   {# FOR INFORMATION ABOUT THE CUSTOM autoaliasattr DIRECTIVE! #}
+   .. autoaliasattr:: {{ fullname }}
 
    {% block classes %}
    {% if classes %}

docs/source/conf.py

@@ -11,6 +11,7 @@
 from pathlib import Path
 
 import manim
+from manim.utils.docbuild.module_parsing import parse_module_attributes
 
 # -- Path setup --------------------------------------------------------------
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -44,6 +45,7 @@
     "sphinxext.opengraph",
     "manim.utils.docbuild.manim_directive",
     "manim.utils.docbuild.autocolor_directive",
+    "manim.utils.docbuild.autoaliasattr_directive",
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
     "sphinxcontrib.programoutput",
@@ -54,7 +56,14 @@
 autosummary_generate = True
 
 # generate documentation from type hints
+ALIAS_DOCS_DICT = parse_module_attributes()[0]
 autodoc_typehints = "description"
+autodoc_type_aliases = {
+    alias_name: f"~manim.{module}.{alias_name}"
+    for module, module_dict in ALIAS_DOCS_DICT.items()
+    for category_dict in module_dict.values()
+    for alias_name in category_dict.keys()
+}
 autoclass_content = "both"
 
 # controls whether functions documented by the autofunction directive

docs/source/contributing/development.rst

@@ -159,6 +159,8 @@ Develop your contribution
 As far as development on your local machine goes, these are the main steps you
 should follow.
 
+.. _polishing-changes-and-submitting-a-pull-request:
+
 Polishing Changes and Submitting a Pull Request
 -----------------------------------------------
 

docs/source/reference_index/utilities_misc.rst

@@ -9,23 +9,25 @@ Module Index
 .. autosummary::
    :toctree: ../reference
 
-   constants
    ~utils.bezier
    ~utils.color
    ~utils.commands
    ~utils.config_ops
-   ~utils.deprecation
+   constants
    ~utils.debug
+   ~utils.deprecation
    ~utils.docbuild
    ~utils.hashing
-   ~utils.ipython_magic
    ~utils.images
+   ~utils.ipython_magic
    ~utils.iterables
    ~utils.paths
    ~utils.rate_functions
    ~utils.simple_functions
    ~utils.sounds
    ~utils.space_ops
+   ~utils.testing
    ~utils.tex
-   ~utils.tex_templates
    ~utils.tex_file_writing
+   ~utils.tex_templates
+   typing

manim/__init__.py

@@ -16,6 +16,7 @@
 from .utils.commands import *
 
 # isort: on
+import numpy as np
 
 from .animation.animation import *
 from .animation.changing import *

manim/_config/cli_colors.py

@@ -4,6 +4,8 @@
 
 from cloup import Context, HelpFormatter, HelpTheme, Style
 
+__all__ = ["parse_cli_ctx"]
+
 
 def parse_cli_ctx(parser: configparser.SectionProxy) -> Context:
     formatter_settings: dict[str, str | int] = {

manim/_config/logger_utils.py

@@ -26,6 +26,8 @@
 if TYPE_CHECKING:
     from pathlib import Path
 
+__all__ = ["make_logger", "parse_theme", "set_file_logger", "JSONFormatter"]
+
 HIGHLIGHTED_KEYWORDS = [  # these keywords are highlighted specially
     "Played",
     "animations",

manim/_config/utils.py

@@ -20,18 +20,24 @@
 import re
 import sys
 from collections.abc import Mapping, MutableMapping
-from enum import EnumMeta
 from pathlib import Path
-from typing import Any, ClassVar, Iterable, Iterator, NoReturn
+from typing import TYPE_CHECKING, Any, ClassVar, Iterable, Iterator, NoReturn
 
 import numpy as np
-from typing_extensions import Self
 
-from .. import constants
-from ..constants import RendererType
-from ..typing import StrPath, Vector3
-from ..utils.color import ManimColor
-from ..utils.tex import TexTemplate, TexTemplateFromFile
+from manim import constants
+from manim.constants import RendererType
+from manim.utils.color import ManimColor
+from manim.utils.tex import TexTemplate, TexTemplateFromFile
+
+if TYPE_CHECKING:
+    from enum import EnumMeta
+
+    from typing_extensions import Self
+
+    from manim.typing import StrPath, Vector3D
+
+__all__ = ["config_file_paths", "make_config_parser", "ManimConfig", "ManimFrame"]
 
 
 def config_file_paths() -> list[Path]:
@@ -1145,22 +1151,22 @@ def frame_x_radius(self, value: float) -> None:
         )
 
     @property
-    def top(self) -> Vector3:
+    def top(self) -> Vector3D:
         """Coordinate at the center top of the frame."""
         return self.frame_y_radius * constants.UP
 
     @property
-    def bottom(self) -> Vector3:
+    def bottom(self) -> Vector3D:
         """Coordinate at the center bottom of the frame."""
         return self.frame_y_radius * constants.DOWN
 
     @property
-    def left_side(self) -> Vector3:
+    def left_side(self) -> Vector3D:
         """Coordinate at the middle left of the frame."""
         return self.frame_x_radius * constants.LEFT
 
     @property
-    def right_side(self) -> Vector3:
+    def right_side(self) -> Vector3D:
         """Coordinate at the middle right of the frame."""
         return self.frame_x_radius * constants.RIGHT
 
@@ -1801,7 +1807,7 @@ class ManimFrame(Mapping):
         "left_side",
         "right_side",
     }
-    _CONSTANTS: ClassVar[dict[str, Vector3]] = {
+    _CONSTANTS: ClassVar[dict[str, Vector3D]] = {
         "UP": np.array((0.0, 1.0, 0.0)),
         "DOWN": np.array((0.0, -1.0, 0.0)),
         "RIGHT": np.array((1.0, 0.0, 0.0)),

manim/animation/speedmodifier.py

@@ -13,6 +13,8 @@
 from ..mobject.mobject import Mobject, Updater, _AnimationBuilder
 from ..scene.scene import Scene
 
+__all__ = ["ChangeSpeed"]
+
 
 class ChangeSpeed(Animation):
     """Modifies the speed of passed animation.