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.rstindex 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** (seehttps://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, parametersand 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 variablelength 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...)