Merge branch 'main' into line_gradient

ManimCommunity · Feb 2, 2024 · 011e5cb · 011e5cb
2 parents 4b5fdc1 + 1520481
commit 011e5cb
Show file tree

Hide file tree

Showing 97 changed files with 2,800 additions and 1,476 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -34,7 +34,7 @@ jobs:
           poetry config virtualenvs.prefer-active-python true
 
       - name: Setup Python ${{ matrix.python }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
           cache: "poetry"
@@ -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)
@@ -143,7 +143,7 @@ jobs:
           $tinyTexPackages = $(python -c "import json;print(' '.join(json.load(open('.github/manimdependency.json'))['windows']['tinytex']))") -Split ' '
           $OriPath = $env:PATH
           echo "Install Tinytex"
-          Invoke-WebRequest "https://github.com/yihui/tinytex-releases/releases/download/daily/TinyTeX-1.zip" -O "$($env:TMP)\TinyTex.zip"
+          Invoke-WebRequest "https://github.com/yihui/tinytex-releases/releases/download/daily/TinyTeX-1.zip" -OutFile "$($env:TMP)\TinyTex.zip"
           Expand-Archive -LiteralPath "$($env:TMP)\TinyTex.zip" -DestinationPath "$($PWD)\ManimCache\LatexWindows"
           $env:Path = "$($PWD)\ManimCache\LatexWindows\TinyTeX\bin\windows;$($env:PATH)"
           tlmgr update --self

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -27,16 +27,16 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
           config-file: ./.github/codeql.yml
           queries: +security-and-quality
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
         with:
           category: "/language:${{ matrix.language }}"
diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
@@ -11,7 +11,7 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Set up Python 3.11
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.11
 
@@ -30,7 +30,7 @@ jobs:
         poetry build
 
     - name: Store artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
           path: dist/*.tar.gz
           name: manim.tar.gz

diff --git a/.github/workflows/release-publish-documentation.yml b/.github/workflows/release-publish-documentation.yml
@@ -12,7 +12,7 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Set up Python 3.11
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: 3.11
 
@@ -40,7 +40,7 @@ jobs:
         tar -czvf ../html-docs.tar.gz *
 
     - name: Store artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
           path: ${{ github.workspace }}/docs/build/html-docs.tar.gz
           name: html-docs.tar.gz

diff --git a/docs/source/_templates/autosummary/module.rst b/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 %}

diff --git a/docs/source/conf.py b/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

diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -38,14 +38,10 @@ To get an overview of what our community is currently working on, check out
 Contributing can be confusing, so here are a few guides:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    contributing/development
-   contributing/docstrings
-   contributing/references
-   contributing/examples
-   contributing/typings
-   contributing/admonitions
+   contributing/docs
    contributing/testing
    contributing/performance
    contributing/internationalization
diff --git a/docs/source/contributing/development.rst b/docs/source/contributing/development.rst
@@ -147,7 +147,7 @@ Develop your contribution
 
    Update the docstrings (the text in triple quotation marks) of any functions
    or classes you change and include them with any new functions you add.
-   See the :doc:`documentation guide <docstrings>` for more information about how we
+   See the :doc:`documentation guide <docs/docstrings>` for more information about how we
    prefer our code to be documented. The content of the docstrings will be
    rendered in the :doc:`reference manual <../reference>`.
 
@@ -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
 -----------------------------------------------
 
@@ -243,7 +245,8 @@ sticks to our coding conventions.
   a look at the built HTML files to see whether the formatting of the documentation
   you added looks as you intended. You can build the documentation locally
   by running ``make html`` from the ``docs`` directory. Make sure you have `Graphviz <https://graphviz.org/>`_
-  installed locally in order to build the inheritance diagrams.
+  installed locally in order to build the inheritance diagrams. See :doc:`docs` for
+  more information.
 
 Finally, if the pipeline passes and you are satisfied with your changes: wait for
 feedback and iterate over any requested changes. You will likely be asked to

diff --git a/docs/source/contributing/docs.rst b/docs/source/contributing/docs.rst
@@ -0,0 +1,83 @@
+====================
+Adding Documentation
+====================
+
+Building the documentation
+--------------------------
+
+When you clone the Manim repository from GitHub, you can access the
+``docs/`` folder which contains the necessary files to build the
+documentation.
+
+To build the docs locally, open a CLI, enter the ``docs/`` folder with the
+``cd`` command and execute the following depending on your OS:
+
+-   Windows: ``./make.bat html``
+-   macOS and Linux: ``make html``
+
+The first time you build the docs, the process will take several
+minutes because it needs to generate all the ``.rst`` (reST:
+reStructured Text) files from scratch by reading and parsing all the
+Manim content. The process becomes much shorter the next time, as it
+rebuilds only the parts which have changed.
+
+
+Sphinx library and extensions
+-----------------------------
+
+Manim uses `Sphinx <https://www.sphinx-doc.org>`_ for building the
+docs. It also makes use of Sphinx extensions such as:
+
+-   `Autodoc: <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
+    imports Manim's Python source code, extracts its docstrings and
+    generates documentation from them.
+-   `Autosummary: <https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html>`_
+    a complement to Autodoc which adds a special directive ``autosummary``,
+    used in Manim to automatically document classes, methods,
+    attributes, functions, module-level variables and exceptions.
+    Autosummary makes use of `Jinja templates <https://jinja.palletsprojects.com/templates/>`_,
+    which Manim defines for autosummarizing classes and modules
+    inside ``docs/source/_templates/``.
+-   `Graphviz extension for Sphinx: <https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html>`_
+    embeds graphs generated by the `Graphviz <https://graphviz.org/>`_
+    module, which must be installed in order to render the
+    inheritance diagrams in the :doc:`/reference`.
+-   `Napoleon: <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_
+    enables Sphinx to read Google style docstrings and, in
+    particular for Manim, `NumPy style docstrings <https://numpydoc.readthedocs.io/en/latest/format.html>`_
+    - see :doc:`docs/docstrings` for more information.
+
+
+Sphinx theme
+------------
+
+The theme used for this website is `Furo <https://sphinx-themes.org/sample-sites/furo/>`_.
+
+
+Custom Sphinx directives
+------------------------
+
+Manim implements **custom directives** for use with Autodoc and Autosummary, which
+are defined in :mod:`~.docbuild`:
+
+.. currentmodule:: manim.utils.docbuild
+
+.. autosummary::
+
+    :toctree: ../reference
+    autoaliasattr_directive
+    autocolor_directive
+    manim_directive
+
+
+Index
+-----
+
+.. toctree::
+   :maxdepth: 2
+
+   docs/admonitions
+   docs/docstrings
+   docs/examples
+   docs/references
+   docs/typings
diff --git a/docs/source/contributing/admonitions.rst → .../source/contributing/docs/admonitions.rst b/docs/source/contributing/admonitions.rst → .../source/contributing/docs/admonitions.rst
diff --git a/docs/source/contributing/docstrings.rst → docs/source/contributing/docs/docstrings.rst b/docs/source/contributing/docstrings.rst → docs/source/contributing/docs/docstrings.rst
diff --git a/docs/source/contributing/examples.rst → docs/source/contributing/docs/examples.rst b/docs/source/contributing/examples.rst → docs/source/contributing/docs/examples.rst
diff --git a/docs/source/contributing/references.rst → docs/source/contributing/docs/references.rst b/docs/source/contributing/references.rst → docs/source/contributing/docs/references.rst
diff --git a/docs/source/contributing/typings.rst → docs/source/contributing/docs/typings.rst b/docs/source/contributing/typings.rst → docs/source/contributing/docs/typings.rst
@@ -40,6 +40,9 @@ Typing guidelines
   pending shape support, using the correct type aliases will help users understand
   which shape should be used.
 
+* For typings of generic collections, check out `this <https://docs.python.org/3/library/collections.abc.html#collections-abstract-base-classes>`_
+  link.
+
 * Always use a type hint of ``None`` for functions that does not return
   a value (this also applies to ``__init__``), e.g.:
 
@@ -57,6 +60,8 @@ Typing guidelines
 * Following `PEP 484 <https://peps.python.org/pep-0484/#the-numeric-tower>`_,
   use ``float`` instead of ``int | float``.
 
+* Use ``x | y`` instead of ``Union[x, y]``
+
 * Mobjects have the typehint ``Mobject``, e.g.:
 
 .. code:: py
@@ -66,16 +71,55 @@ Typing guidelines
         return self.set_color(mobject.get_color())
 
 * Always parametrize generics (``list[int]`` instead of ``list``,
-  ``type[Any]`` instead of ``type``, etc.). This also applies to callables:
+  ``type[Any]`` instead of ``type``, etc.). This also applies to callables.
 
 .. code:: py
 
     rate_func: Callable[[float], float] = lambda t: smooth(1 - t)
 
+* Use ``TypeVar`` when you want to "link" type hints as being the same type.
+  Consider ``Mobject.copy``, which returns a new instance of the same class.
+  It would be type-hinted as:
+
+.. code:: py
+
+    T = TypeVar("T")
+
+
+    def copy(self: T) -> T:
+        ...
+
+* Use ``typing.Iterable`` whenever the function works with *any* iterable, not a specific type.
+
+* If the function returns a container of a specific length each time, consider using ``tuple`` instead of ``list``.
+
+.. code:: py
+
+   def foo() -> tuple[float, float, float]:
+       return (0, 0, 0)
+
+* If a function works with a parameter as long as said parameter has a ``__getitem__``, ``__iter___`` and ``__len__`` method,
+  the typehint of the parameter should be ``collections.abc.Mapping``. If it also supports ``__setitem__`` and/or ``__delitem__``, it
+  should be marked as ``collections.abc.MutableMapping``.
+
+* Typehinting something as ``object`` means that only attributes available on every Python object should be accessed,
+  like ``__str__`` and so on. On the other hand, literally any attribute can be accessed on a variable with the ``Any`` typehint -
+  it's more freeing than the ``object`` typehint, and makes mypy stop typechecking the variable. Note that whenever possible,
+  try to keep typehints as specific as possible.
+
+* If objects are imported purely for type hint purposes, keep it under an ``if typing.TYPE_CHECKING`` guard, to prevent them from
+  being imported at runtime (helps library performance). Do not forget to use the ``from __future__ import annotations`` import to avoid having runtime ``NameError`` exceptions.
+
+.. code:: py
+
+   from typing import TYPE_CHECKING
+
+   if TYPE_CHECKING:
+       from manim.typing import Vector3
+   # type stuff with Vector3
+
 Missing Sections for typehints are:
 -----------------------------------
 
 * Mypy and numpy import errors: https://realpython.com/python-type-checking/#running-mypy
-* When to use ``object`` vs ``Any``
-* The use of a TypeVar on the type hints for ``copy()``.
-* The definition and use of Protocols (like ``Sized``, ``Sequence``, ``Iterable``...)
+* Explain ``mypy.ini`` (see above link)
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -94,7 +94,7 @@ Basic Concepts
             self.add(image, image.background_rectangle)
 
 .. manim:: BooleanOperations
-    :ref_classes: Union Intersection Exclusion
+    :ref_classes: Union Intersection Exclusion Difference
 
     class BooleanOperations(Scene):
         def construct(self):

diff --git a/docs/source/installation/docker.rst b/docs/source/installation/docker.rst
@@ -45,7 +45,7 @@ modify to your liking. First, run
 
 .. code-block:: sh
 
-   docker run -it --name my-manim-container -v "/full/path/to/your/directory:/manim" manimcommunity/manim /bin/bash
+   docker run -it --name my-manim-container -v "/full/path/to/your/directory:/manim" manimcommunity/manim bash
 
 
 to obtain an interactive shell inside your container allowing you

diff --git a/docs/source/reference_index/utilities_misc.rst b/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
diff --git a/manim/__init__.py b/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 *