Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Added documentation guidelines for type hints (#1338)

kolibril13642b7683b28c
diff --git a/docs/source/contributing/documentation.rst b/docs/source/contributing/documentation.rst
index f8c6bac5c..90c20c779 100644
--- a/docs/source/contributing/documentation.rst
+++ b/docs/source/contributing/documentation.rst
@@ -184,8 +184,8 @@ Example:
.. _types:
-Types
------
+Reference to types in documentaion
+----------------------------------
Always specify types with the correct **role** (see
https://www.sphinx-doc.org/en/1.7/domains.html#python-roles) for the
@@ -232,8 +232,8 @@ Example: ``:class:`~.Animation`​``, ``:meth:`~.VMobject.set_color`​``,
Example: ``:class:`numpy.ndarray`​`` for a numpy ndarray.
-Type specifications
-~~~~~~~~~~~~~~~~~~~
+Reference type specifications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**The following instructions refer to types of attributes, parameters
and return values.** When specifying a type mid-text, it does not
@@ -317,3 +317,77 @@ elements that are either a ``str`` or ``None``;
``Tuple[:class:`str`, :class:`int`]`` for a tuple of type
``(str, int)``; ``Tuple[:class:`int`, ...]`` for a tuple of variable
length with only integers.
+
+
+Adding type hints to functions and parameters
+---------------------------------------------
+
+If you've never used type hints before, this is a good place to get started:
+https://realpython.com/python-type-checking/#hello-types.
+
+When adding type hints to manim, there are some guidelines that should be followed:
+
+* Coordinates have the typehint ``Sequence[float]``, e.g.
+
+.. code:: py
+
+ def set_points_as_corners(self, points: Sequence[float]) -> "VMobject":
+ """Given an array of points, set them as corner of the Vmobject."""
+* ``**kwargs`` has no typehint
+
+* Mobjects have the typehint "Mobject", e.g.
+
+.. code:: py
+
+ def match_color(self, mobject: "Mobject"):
+ """Match the color with the color of another :class:`~.Mobject`."""
+ return self.set_color(mobject.get_color())
+* Colors have the typehint ``Color``, e.g.
+
+.. code:: py
+
+ def set_color(self, color: Color = YELLOW_C, family: bool = True):
+ """Condition is function which takes in one arguments, (x, y, z)."""
+* As ``float`` and ``Union[int, float]`` are the same, use only ``float``
+
+* For numpy arrays use the typehint ``np.ndarray``
+
+* Functions that does not return a value should get the type hint ``None``. (This annotations help catch the kinds of subtle bugs where you are trying to use a meaningless return value. )
+
+.. code:: py
+
+ def height(self, value) -> None:
+ self.scale_to_fit_height(value)
+* Parameters that are None by default should get the type hint ``Optional``
+
+.. code:: py
+
+ def rotate(
+ self,
+ angle,
+ axis=OUT,
+ about_point: Optional[Sequence[float]] = None,
+ **kwargs,
+ ):
+ pass
+
+
+* the .__init__() method always should have None as its return type.
+
+* functions and lambda functions should get the typehint ``Callable``
+
+.. code:: py
+
+ rate_func: Callable[[float], float] = lambda t: smooth(1 - t)
+
+* numpy arrays can get type hints with ``np.ndarray``
+
+Missing Sections
+----------------
+* Tools for typehinting
+* Link to MyPy
+* Mypy and numpy import errors: https://realpython.com/python-type-checking/#running-mypy
+* Where to find the alias
+* When to use Object and when to use "Object".
+* The use of a TypeVar on the type hints for copy().
+* The definition and use of Protocols (like Sized, or Sequence, or Iterable...)