Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Added testing/documentation from GitHub Wiki to Sphinx Docs (#1137)

Jason Villanuevae384ce93f2fc
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4e882a60a..3c820ad6d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -11,4 +11,3 @@ repos:
rev: 3.9.0
hooks:
- id: flake8
- args: [--max-line-length=88, --extend-ignore=extend-ignore=E203, E266, F841, B007, B006, F405, F403, F401, F821, B008, E501, B009, B010, E731, RST304, D400, D401, D205, D105, D103, RST210, RST303, D102, D102, D107, RST212, D200, D100, D101, D412, D202, RST305, RST301, D301, RST213, D104, RST201, RST215, RST203, D104, D209, RST205, D402, D210, RST202, A003, W605,]
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
index ec650585f..208d58e83 100644
--- a/docs/source/contributing.rst
+++ b/docs/source/contributing.rst
@@ -2,7 +2,7 @@
Contributing
############
-Thank you for contributing to Manim! However you have decided to contribute
+Thank you for your interest in contributing to Manim! However you have decided to contribute
or interact with the community, please always be civil and respect other
members of the community. If you haven't read our :doc:`code of conduct<conduct>`,
do so here. Manim is Free and Open Source Software (FOSS) for mathematical
@@ -24,264 +24,11 @@ some are detailed below:
-Manim Development Process
-=========================
+Contributing can be confusing, so here's a few guides:
-For first-time contributors
----------------------------
-#. Install git:
+.. toctree::
+ :maxdepth: 2
- For instructions see https://git-scm.com/.
-
-
-#. Fork the project. Go to https://github.com/ManimCommunity/manim and
- click the "fork" button to create your own copy of the project. You will
- need a GitHub account. This will allow you to make a "pull request" (PR)
- to the ManimCommunity repo later on.
-
-#. Clone your fork to your local computer:
-
- .. code-block:: shell
-
- git clone https://github.com/<your-username>/manim.git
-
- GitHub will provide both a SSH (``[email protected]:<your-username>/manim.git``) and
- HTTPS (``https://github.com/<your-username>/manim.git``) URL for cloning.
- You can use SSH if you have SSH keys setup.
-
- .. WARNING::
-
- Do not clone the ManimCommunity repository. You must clone your own
- fork.
-
-#. Change the directory to enter the project folder:
-
- .. code-block:: shell
-
- cd manim
-
-#. Add the upstream repository, ManimCommunity:
-
- .. code-block:: shell
-
- git remote add upstream https://github.com/ManimCommunity/manim.git
-
-#. Now, ``git remote -v`` should show two remote repositores named:
-
- - ``origin``, your forked repository
- - ``upstream`` the ManimCommunity repository
-
-#. Install Manim:
-
- - See our :doc:`instructions for developers<installation/for_dev>` for
- details and continue here afterwards.
-
-#. Install Pre-Commit (recommended):
-
- .. code-block:: shell
-
- poetry run pre-commit install
-
- This is optional and will ensure during development that each of your
- commit is properly formatted against our formatter, ``black``.
-
-You are now ready to work on manim!
-
-Develop your contribution
--------------------------
-
-#. Checkout your local repository's master branch and pull the latest
- changes from ManimCommunity, `upstream`, into your local repository:
-
- .. code-block:: shell
-
- git checkout master
- git pull --rebase upstream master
-
-#. Create a branch for the changes you want to work on rather than working
- off of master:
-
- .. code-block:: shell
-
- git checkout -b <new branch name> upstream/master
-
- This ensures you can easily update your local repository's master with the
- first step and switch branches to work on multiple features.
-
-#. Write some awesome code!
-
- You're ready to make changes in your local repository's branch.
- You can add local files you've changed with in the current directory with
- ``git add .``, or add specific files with
-
- .. code-block:: shell
-
- git add <file/directory>
-
- and commit these changes to your local history with ``git commit``. If you
- have installed pre-commit, your commit will succeed only if none of the
- hooks fail.
-
- .. tip::
-
- When crafting commit messages, it is highly recommended that
- you adhere to `these guidelines <https://www.conventionalcommits.org/en/v1.0.0/>`_.
-
-#. Add new or update existing tests.
-
- Depending on your changes, you may need to update or add new tests. For new
- features, it is required that you include tests with your PR. Details of
- our testing system are explained in the `corresponding Wiki Entry <https://github.com/ManimCommunity/manim/wiki/Testing>`_.
-
-
-#. Update docstrings and documentation:
-
- 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.
- There is a `Wiki Entry for Documentation <https://github.com/ManimCommunity/manim/wiki/Documentation-guidelines-(WIP)>`_
- with 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>`.
-
- .. tip::
-
- Use the :mod:`manim directive for Sphinx <.manim_directive>` to add examples
- to the documentation!
-
- .. autosummary::
- :toctree: reference
-
- manim_directive
-
-As far as development on your local machine goes, these are the main steps you
-should follow.
-
-Polishing Changes and Submitting a Pull Request
------------------------------------------------
-
-As soon as you are ready to share your local changes with the community
-so that they can be discussed, go through the following steps to open a
-pull request. A pull request signifies to the ManimCommunity organization,
-"Here's some changes I wrote; I think it's worthwhile for you to maintain
-them."
-
-.. NOTE::
-
- You do not need to have everything (code / documentation / tests) complete
- to open a pull request (PR). If the PR is still under development, please
- mark it as a draft. Community developers will still be able to review the
- changes, discuss yet-to-be-implemented changes, and offer advice; however,
- the more complete your PR, the quicker it will be merged.
-
-#. Update your fork on GitHub to reflect your local changes:
-
- .. code-block:: shell
-
- git push -u origin <branch name>
-
- Doing so creates a new branch on your remote fork, `origin`, with the
- contents of your local repository on GitHub. In subsequent pushes, this
- local branch will track the branch `origin` and ``git push`` is enough.
-
-
-#. Make a pull request (PR) on GitHub.
-
- In order to make the ManimCommunity development team aware of your changes,
- you can make a PR to the ManimCommunity repository from your fork.
-
- .. WARNING::
-
- Make sure to select ``ManimCommunity/manim`` instead of ``3b1b/manim``
- as the base repository!
-
- Choose the branch from your fork as the head repository - see the
- screenshot below.
-
- .. image:: /_static/pull-requests.PNG
- :align: center
-
- Please make sure you follow the template (this is the default
- text you are shown when first opening the 'New Pull Request' page).
-
-
-Your changes are eligible to be merged if:
-
-#. there are no merge conflicts
-#. the tests in our pipeline pass
-#. at least one (two for more complex changes) Community Developer approves the changes
-
-You can check for merge conflicts between the current upstream/master and
-your branch by executing ``git pull upstream master`` locally. If this
-generates any merge conflicts, you need to resolve them and push an
-updated version of the branch to your fork of the repository.
-
-Our pipeline consists of a series of different tests that ensure
-that manim still works as intended and that the code you added
-sticks to our coding conventions.
-
-- *Code style*: We use the code style imposed
- by `Black <https://black.readthedocs.io/en/stable/>`_. The pipeline
- makes sure that the (Python) files changed in your pull request
- also adhere to this code style. If this step of the pipeline fails,
- fix your code style by running ``black <file or directory>`` to
- automatically format your files.
-
-- *Tests*: The pipeline runs manim's test suite on different operating systems
- (the latest versions of Ubuntu, MacOS, and Windows) for different versions of Python.
- The test suite consists of two different kinds of tests: integration tests
- and doctests. You can run them locally by executing ``poetry run pytest``
- and ``poetry run pytest --doctest-modules manim``, respectively, from the
- root directory of your cloned fork.
-
-- *Documentation*: We also build a version of the documentation corresponding
- to your pull request. Make sure not to introduce any Sphinx errors, and have
- a look at the built HTML files to see whether the formatting of the documentation
- you added looks like you intended. You can build the documentation locally
- by running ``pip install -r docs/requirements.txt``
- and then running ``make html``.
-
-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
-edit or modify your PR in one way or another during this process. This is not
-an indictment of your work, but rather a strong signal that the community
-wants to merge your changes! Once approved, your changes may be merged!
-
-Further useful guidelines
-=========================
-
-#. When submitting a PR, please make special note of whether your proposed
- changes will result in breaking changes.
-
-#. When submitting a PR, make sure that your proposed changes are as general as
- possible, and ready to be taken advantage of by all of manim's users. In
- particular, leave out any machine-specific configurations, or any personal
- information it may contain.
-
-#. If you are a maintainer, please label issues and PRs appropriately and
- frequently.
-
-#. When opening a new issue, if there are old issues that are related, link
- them in your new issue (even if the old ones are closed).
-
-#. When submitting a code review, it is highly recommended that you adhere to
- `these general guidelines <https://conventionalcomments.org/>`_.
-
-#. If you find stale or inactive issues that seem to be irrelevant, please post
- a comment saying 'This issue should be closed', and a community developer
- will take a look.
-
-#. Please do as much as possible to keep issues, PRs, and development in
- general as tidy as possible.
-
-
-You can find examples for the ``docs`` in several places:
-the :doc:`Example Gallery<examples>`, :doc:`Tutorials<tutorials>`,
-and :doc:`Reference Classes<reference>`.
-
-In case you are contributing, please have a look at this flowchart:
-
-.. raw:: html
-
- <div class="mxgraph" style="max-width:100%;border:1px solid transparent;" data-mxgraph="{&quot;highlight&quot;:&quot;#0000ff&quot;,&quot;nav&quot;:true,&quot;resize&quot;:true,&quot;toolbar&quot;:&quot;zoom layers lightbox&quot;,&quot;edit&quot;:&quot;_blank&quot;,&quot;url&quot;:&quot;https://drive.google.com/uc?id=1aKyJTloYB97IhrzwqEENOu-WQyuVWMjM&amp;export=download&quot;}"></div>
- <script type="text/javascript" src="https://viewer.diagrams.net/embed2.js?&fetch=https%3A%2F%2Fdrive.google.com%2Fuc%3Fid%3D1aKyJTloYB97IhrzwqEENOu-WQyuVWMjM%26export%3Ddownload"></script>
-
-**Thank you for contributing!**
+ contributing/development
+ contributing/documentation
+ contributing/testing
diff --git a/docs/source/contributing/development.rst b/docs/source/contributing/development.rst
new file mode 100644
index 000000000..0c0587571
--- /dev/null
+++ b/docs/source/contributing/development.rst
@@ -0,0 +1,262 @@
+=========================
+Manim Development Process
+=========================
+
+For first-time contributors
+---------------------------
+#. Install git:
+
+ For instructions see https://git-scm.com/.
+
+
+#. Fork the project. Go to https://github.com/ManimCommunity/manim and
+ click the "fork" button to create your own copy of the project. You will
+ need a GitHub account. This will allow you to make a "pull request" (PR)
+ to the ManimCommunity repo later on.
+
+#. Clone your fork to your local computer:
+
+ .. code-block:: shell
+
+ git clone https://github.com/<your-username>/manim.git
+
+ GitHub will provide both a SSH (``[email protected]:<your-username>/manim.git``) and
+ HTTPS (``https://github.com/<your-username>/manim.git``) URL for cloning.
+ You can use SSH if you have SSH keys setup.
+
+ .. WARNING::
+
+ Do not clone the ManimCommunity repository. You must clone your own
+ fork.
+
+#. Change the directory to enter the project folder:
+
+ .. code-block:: shell
+
+ cd manim
+
+#. Add the upstream repository, ManimCommunity:
+
+ .. code-block:: shell
+
+ git remote add upstream https://github.com/ManimCommunity/manim.git
+
+#. Now, ``git remote -v`` should show two remote repositores named:
+
+ - ``origin``, your forked repository
+ - ``upstream`` the ManimCommunity repository
+
+#. Install Manim:
+
+ - See our :doc:`instructions for developers<installation/for_dev>` for
+ details and continue here afterwards.
+
+#. Install Pre-Commit (recommended):
+
+ .. code-block:: shell
+
+ poetry run pre-commit install
+
+ This is optional and will ensure during development that each of your
+ commit is properly formatted against our formatter, ``black``.
+
+You are now ready to work on manim!
+
+Develop your contribution
+-------------------------
+
+#. Checkout your local repository's master branch and pull the latest
+ changes from ManimCommunity, ``upstream``, into your local repository:
+
+ .. code-block:: shell
+
+ git checkout master
+ git pull --rebase upstream master
+
+#. Create a branch for the changes you want to work on rather than working
+ off of master:
+
+ .. code-block:: shell
+
+ git checkout -b <new branch name> upstream/master
+
+ This ensures you can easily update your local repository's master with the
+ first step and switch branches to work on multiple features.
+
+#. Write some awesome code!
+
+ You're ready to make changes in your local repository's branch.
+ You can add local files you've changed with in the current directory with
+ ``git add .``, or add specific files with
+
+ .. code-block:: shell
+
+ git add <file/directory>
+
+ and commit these changes to your local history with ``git commit``. If you
+ have installed pre-commit, your commit will succeed only if none of the
+ hooks fail.
+
+ .. tip::
+
+ When crafting commit messages, it is highly recommended that
+ you adhere to `these guidelines <https://www.conventionalcommits.org/en/v1.0.0/>`_.
+
+#. Add new or update existing tests.
+
+ Depending on your changes, you may need to update or add new tests. For new
+ features, it is required that you include tests with your PR. Details of
+ our testing system are explained in the :doc:`testing guide <testing>`.
+
+
+#. Update docstrings and documentation:
+
+ 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 <documentation>` 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>`.
+
+ .. tip::
+
+ Use the :mod:`manim directive for Sphinx <.manim_directive>` to add examples
+ to the documentation!
+
+ .. autosummary::
+ :toctree: reference
+
+ manim_directive
+
+As far as development on your local machine goes, these are the main steps you
+should follow.
+
+Polishing Changes and Submitting a Pull Request
+-----------------------------------------------
+
+As soon as you are ready to share your local changes with the community
+so that they can be discussed, go through the following steps to open a
+pull request. A pull request signifies to the ManimCommunity organization,
+"Here's some changes I wrote; I think it's worthwhile for you to maintain
+them."
+
+.. NOTE::
+
+ You do not need to have everything (code / documentation / tests) complete
+ to open a pull request (PR). If the PR is still under development, please
+ mark it as a draft. Community developers will still be able to review the
+ changes, discuss yet-to-be-implemented changes, and offer advice; however,
+ the more complete your PR, the quicker it will be merged.
+
+#. Update your fork on GitHub to reflect your local changes:
+
+ .. code-block:: shell
+
+ git push -u origin <branch name>
+
+ Doing so creates a new branch on your remote fork, ``origin``, with the
+ contents of your local repository on GitHub. In subsequent pushes, this
+ local branch will track the branch ``origin`` and ``git push`` is enough.
+
+
+#. Make a pull request (PR) on GitHub.
+
+ In order to make the ManimCommunity development team aware of your changes,
+ you can make a PR to the ManimCommunity repository from your fork.
+
+ .. WARNING::
+
+ Make sure to select ``ManimCommunity/manim`` instead of ``3b1b/manim``
+ as the base repository!
+
+ Choose the branch from your fork as the head repository - see the
+ screenshot below.
+
+ .. image:: /_static/pull-requests.PNG
+ :align: center
+
+ Please make sure you follow the template (this is the default
+ text you are shown when first opening the 'New Pull Request' page).
+
+
+Your changes are eligible to be merged if:
+
+#. there are no merge conflicts
+#. the tests in our pipeline pass
+#. at least one (two for more complex changes) Community Developer approves the changes
+
+You can check for merge conflicts between the current upstream/master and
+your branch by executing ``git pull upstream master`` locally. If this
+generates any merge conflicts, you need to resolve them and push an
+updated version of the branch to your fork of the repository.
+
+Our pipeline consists of a series of different tests that ensure
+that manim still works as intended and that the code you added
+sticks to our coding conventions.
+
+- *Code style*: We use the code style imposed
+ by `Black <https://black.readthedocs.io/en/stable/>`_. The pipeline
+ makes sure that the (Python) files changed in your pull request
+ also adhere to this code style. If this step of the pipeline fails,
+ fix your code style by running ``black <file or directory>`` to
+ automatically format your files.
+
+- *Tests*: The pipeline runs manim's test suite on different operating systems
+ (the latest versions of Ubuntu, MacOS, and Windows) for different versions of Python.
+ The test suite consists of two different kinds of tests: integration tests
+ and doctests. You can run them locally by executing ``poetry run pytest``
+ and ``poetry run pytest --doctest-modules manim``, respectively, from the
+ root directory of your cloned fork.
+
+- *Documentation*: We also build a version of the documentation corresponding
+ to your pull request. Make sure not to introduce any Sphinx errors, and have
+ a look at the built HTML files to see whether the formatting of the documentation
+ you added looks like you intended. You can build the documentation locally
+ by running ``pip install -r docs/requirements.txt``
+ and then running ``make html``.
+
+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
+edit or modify your PR in one way or another during this process. This is not
+an indictment of your work, but rather a strong signal that the community
+wants to merge your changes! Once approved, your changes may be merged!
+
+Further useful guidelines
+=========================
+
+#. When submitting a PR, please make special note of whether your proposed
+ changes will result in breaking changes.
+
+#. When submitting a PR, make sure that your proposed changes are as general as
+ possible, and ready to be taken advantage of by all of manim's users. In
+ particular, leave out any machine-specific configurations, or any personal
+ information it may contain.
+
+#. If you are a maintainer, please label issues and PRs appropriately and
+ frequently.
+
+#. When opening a new issue, if there are old issues that are related, link
+ them in your new issue (even if the old ones are closed).
+
+#. When submitting a code review, it is highly recommended that you adhere to
+ `these general guidelines <https://conventionalcomments.org/>`_.
+
+#. If you find stale or inactive issues that seem to be irrelevant, please post
+ a comment saying 'This issue should be closed', and a community developer
+ will take a look.
+
+#. Please do as much as possible to keep issues, PRs, and development in
+ general as tidy as possible.
+
+
+You can find examples for the ``docs`` in several places:
+the :doc:`Example Gallery<examples>`, :doc:`Tutorials<tutorials>`,
+and :doc:`Reference Classes<reference>`.
+
+In case you are contributing, please have a look at this flowchart:
+
+.. raw:: html
+
+ <div class="mxgraph" style="max-width:100%;border:1px solid transparent;" data-mxgraph="{&quot;highlight&quot;:&quot;#0000ff&quot;,&quot;nav&quot;:true,&quot;resize&quot;:true,&quot;toolbar&quot;:&quot;zoom layers lightbox&quot;,&quot;edit&quot;:&quot;_blank&quot;,&quot;url&quot;:&quot;https://drive.google.com/uc?id=1aKyJTloYB97IhrzwqEENOu-WQyuVWMjM&amp;export=download&quot;}"></div>
+ <script type="text/javascript" src="https://viewer.diagrams.net/embed2.js?&fetch=https%3A%2F%2Fdrive.google.com%2Fuc%3Fid%3D1aKyJTloYB97IhrzwqEENOu-WQyuVWMjM%26export%3Ddownload"></script>
+
+**Thank you for contributing!**
diff --git a/docs/source/contributing/documentation.rst b/docs/source/contributing/documentation.rst
new file mode 100644
index 000000000..b9aaa377d
--- /dev/null
+++ b/docs/source/contributing/documentation.rst
@@ -0,0 +1,316 @@
+====================
+Adding Documentation
+====================
+
+When submitting a new class through a PR, or any changes in general,
+there should be documentation where possible. Here are the guidelines
+for writing it.
+
+Formatting and Running Tests
+----------------------------
+
+Please begin the description of the class/function in the same line as
+the 3 quotes:
+
+.. code:: py
+
+ def do_this():
+ """This is correct.
+ (...)
+ """
+
+ def dont_do_this():
+ """
+ This is incorrect.
+ (...)
+ """
+
+NumPy Format
+------------
+
+Use the numpy format for sections and formatting - see
+https://numpydoc.readthedocs.io/en/latest/format.html.
+
+This includes:
+
+1. The usage of ``Attributes`` to specify ALL ATTRIBUTES that a
+ class can have, their respective types and a brief (or long, if
+ needed) description. (See more on :ref:`_types`)
+
+Also, ``__init__`` parameters should be specified as ``Parameters`` **on
+the class docstring**, *rather than under* ``__init__``. Note that this
+can be omitted if the parameters and the attributes are the exact same
+(i.e., dataclass) - priority should be given to the ``Attributes``
+section, in this case, which must **always be present**, unless the
+class specifies no attributes at all. (See more on Parameters in number
+2 of this list.)
+
+Example:
+
+.. code:: py
+
+ class MyClass:
+ """My cool class. Long or short (whatever is more appropriate) description here.
+
+ Parameters
+ ----------
+ name : :class:`str`
+ The class's name.
+ id : :class:`int`
+ The class's id.
+ mobj : Optional[:class:`~.Mobject`], optional
+ The mobject linked to this instance. Defaults to `Mobject()` \
+ (is set to that if `None` is specified).
+
+ Attributes
+ ----------
+ name : :class:`str`
+ The user's name.
+ id : :class:`int`
+ The user's id.
+ singleton : :class:`MyClass`
+ Something.
+ mobj : :class:`~.Mobject`
+ The mobject linked to this instance.
+ """
+
+ def __init__(name, id, singleton, mobj = None): # in-code typehints are optional for now
+ ...
+
+2. The usage of ``Parameters`` on functions in order to specify how
+ every parameter works and what it does. This should be excluded if
+ the function has no parameters. Note that you **should not** specify
+ the default value of the parameter on the type. On the documentation
+ render, this is already specified on the function's signature. If you
+ need to indicate a further consequence of value omission or simply
+ want to specify it on the docs, make sure to **specify it in the
+ parameter's DESCRIPTION**.
+
+See an example on list item 4.
+
+.. NOTE::
+
+ When documenting varargs (args and kwargs), make sure to
+ document them by listing the possible types of each value specified,
+ like this:
+
+::
+
+ Parameters
+ ----------
+ args : Union[:class:`int`, :class:`float`]
+ The args specified can be either an int or a float.
+ kwargs : :class:`float`
+ The kwargs specified can only be a float.
+
+Note that, if the kwargs expect specific values, those can be specified
+in a section such as ``Other Parameters``:
+
+::
+
+ Other Parameters
+ ----------------
+ kwarg_param_1 : :class:`int`
+ Parameter documentation here
+ (etc)
+
+3. The usage of ``Returns`` to indicate what is the type of this
+ function's return value and what exactly it returns (i.e., a brief -
+ or long, if needed - description of what this function returns). Can
+ be omitted if the function does not explicitly return (i.e., always
+ returns ``None`` because ``return`` is never specified, and it is
+ very clear why this function does not return at all). In all other
+ cases, it should be specified.
+
+See an example on list item 4.
+
+4. The usage of ``Examples`` in order to specify an example of usage of
+ a function **is highly encouraged** and, in general, should be
+ specified for *every function* unless its usage is **extremely
+ obvious**, which can be debatable. Even if it is, it's always a good
+ idea to add an example in order to give a better orientation to the
+ documentation user. Use the following format for Python code:
+
+ .. code:: rst
+
+ ::
+
+ # python code here
+
+**NOTE: Also, if this is a video- or animation-related change, please
+try to add an example GIF or video if possible for demonstration
+purposes.**
+
+Make sure to be as explicit as possible in your documentation. We all
+want the users to have an easier time using this library.
+
+Example:
+
+.. code:: py
+
+ def my_function(thing, other, name, *, d, test=45): # typings are optional for now
+ """My cool function. Builds and modifies an :class:`EpicClassInThisFile` instance with the given parameters.
+
+ Parameters
+ ----------
+ thing : :class:`int`
+ Specifies the index of life.
+ other : :class:`numpy.ndarray`
+ Specifies something cool.
+ name : :class:`str`
+ Specifies my name.
+ d : :class:`~.SomeClassFromFarAway`
+ Sets thing D to this value.
+ test : :class:`int`, optional
+ Defines the amount of times things should be tested. \
+ Defaults to 45, because that is almost the meaning of life.
+
+ Returns
+ -------
+ :class:`EpicClassInThisFile`
+ The generated EpicClass with the specified attributes and modifications.
+
+ Examples
+ --------
+ Normal usage::
+
+ my_function(5, np.array([1, 2, 3]), "Chelovek", d=SomeClassFromFarAway(cool=True), test=5)
+ """
+ # code...
+ pass
+
+.. _types:
+
+Types
+-----
+
+Always specify types with the correct **role** (see
+https://www.sphinx-doc.org/en/1.7/domains.html#python-roles) for the
+sake of proper rendering. E.g.: Use ``:class:`int``` to refer to an int
+type, and in general ``:class:`<path>`​`` to refer to a certain class
+(see ``Path specification`` below). See after for more specific
+instructions.
+
+Path specifications
+~~~~~~~~~~~~~~~~~~~
+
+1. If it's on stdlib: Use ``<name>`` directly. If it's a class, just the
+ name is enough. If it's a method (``:meth:``) or attribute
+ (``:attr:``), dotted names may be used (e.g.
+ ``:meth:`str.to_lower`​``).
+
+Example: ``:class:`int`​``, ``:class:`str`​``, ``:class:`float`​``,
+``:class:`bool`​``
+
+2. If it's on the same file as the docstring or, for methods and
+ attributes, under the same class, then the name may also be specified
+ directly.
+
+Example: ``:class:`MyClass`​`` referring to a class in the same file;
+``:meth:`push`​`` referring to a method in the same class;
+``:meth:`MyClass.push`​`` referring to a method in a different class in
+the same file; ``:attr:`color`​`` referring to an attribute in the same
+class; ``:attr:`MyClass.color`​`` referring to an attribute in a
+different class in the same file.
+
+3. If it's on a different file, then you may either use the full dotted
+ name (e.g. ``~manim.animations.Animation``) or simply use the
+ shortened way (``~.Animation``). Note that, if there is ambiguity,
+ then the full dotted name must be used where the actual class can't
+ be deduced. Also note the ``~`` before the path - this is so that it
+ displays just ``Animation`` instead of the full location in the
+ rendering. It can be removed for disambiguation purposes only.
+
+Example: ``:class:`~.Animation`​``, ``:meth:`~.VMobject.set_color`​``,
+``:attr:`~.VMobject.color`​``
+
+4. If it's a class from a different module, specify the full dotted
+ syntax.
+
+Example: ``:class:`numpy.ndarray`​`` for a numpy ndarray.
+
+Type specifications
+~~~~~~~~~~~~~~~~~~~
+
+**The following instructions refer to types of attributes, parameters
+and return values.** When specifying a type mid-text, it does not
+necessarily have to be typeset. However, if it's a class name, a method,
+or an enum's attribute/variant, then it is recommended to be typeset at
+least on the first occurrence of the name, so that the users can quickly
+jump to the related documentation.
+
+1. Class names should be wrapped in ``:class:`path_goes_here`​``. See
+ examples in the subsection above.
+2. Method names should be wrapped in ``:meth:`path_goes_here`​``. See
+ examples in the subsection above.
+3. Attribute names should be wrapped in ``:attr:`path_goes_here`​``. See
+ examples in the subsection above.
+4. If ``None`` can also be specified, use ``Optional[type]``, where
+ ``type`` must follow the guidelines in the current section.
+
+Example: ``Optional[:class:`str`]`` means you can either specify a
+``str`` or ``None``.
+
+5. If more than one type is possible, use
+ ``Union[type_1, type_2, (...), type_n]``, where all the ``type_n``
+ must follow the guidelines in the current section. Note that, if one
+ of these types is ``None``, then the Union should be wrapped with
+ ``Optional`` instead.
+
+Example: ``Union[:class:`str`, :class:`int`]`` for either ``str`` or
+``int``. ``Optional[Union[:class:`int`, :class:`bool`]]`` for either
+``int``, ``bool`` or ``None``.
+
+6. **Dictionaries:** Use ``Dict[key_type, value_type]``, where
+ ``key_type`` and ``value_type`` must follow the guidelines in the
+ current section.
+
+Example: ``Dict[:class:`str`, :class:`~.Mobject`]`` is a dictionary that
+maps strings to Mobjects.
+``Dict[:class:`str`, Union[:class:`int`, :class:`MyClass`]]`` is a
+dictionary that maps a string to either an int or an instance of
+``MyClass``.
+
+7. **If the parameter is a list:** Note that it is very rare to require
+ the parameter to be exactly a ``list`` type. One could usually
+ specify a ``tuple`` instead, for example. So, in order to cover all
+ cases, consider:
+
+ 1. If the parameter only needs to be an ``Iterable``, i.e., if the
+ function only requires being able to iterate over this parameter's
+ value (e.g. can be a ``list``, ``tuple``, ``str``, but also
+ ``zip()``, ``iter()`` and so on), then specify
+ ``Iterable[type_here]``, where ``type_here`` is the type of the
+ iterable's yielded elements and should follow the format in the
+ present section (``Type specifications``).
+
+ Example: ``Iterable[:class:`str`]`` for any iterable of strings;
+ ``Iterable[:class:`~.Mobject`]`` for an iterable of Mobjects; etc.
+
+ 2. If you require being able to index the parameter (i.e. ``x[n]``)
+ or retrieve its length (i.e. ``len(x)``), or even just pass it to
+ a function that requires any of those, then specify ``Sequence``,
+ which allows any list-like object to be specified (e.g. ``list``,
+ ``tuple``...)
+
+ Example: ``Sequence[:class:`str`]`` for a sequence of strings;
+ ``Sequence[Union[:class:`str`, :class:`int`]]`` for a sequence of
+ integers or strings.
+
+ 3. If you EXPLICITLY REQUIRE it to be a ``list`` for some reason,
+ then use ``List[type]``, where ``type`` is the type that any
+ element in the list will have. It must follow the guidelines in
+ the current section.
+
+8. **If the return type is a list or tuple:** Specify ``List[type]`` for
+ a list, ``Tuple[type_a, type_b, (...), type_n]`` for a tuple (if the
+ elements are all different) or ``Tuple[type, ...]`` (if all elements
+ have the same type). Each ``type_n`` on those representations
+ correspond to elements in the returned list/tuple, and must follow
+ the guidelines in the current section.
+
+Example: ``List[Optional[:class:`str`]]`` for a list that returns
+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.
diff --git a/docs/source/contributing/reference/manim_directive.ManimDirective.rst b/docs/source/contributing/reference/manim_directive.ManimDirective.rst
new file mode 100644
index 000000000..171d574ed
--- /dev/null
+++ b/docs/source/contributing/reference/manim_directive.ManimDirective.rst
@@ -0,0 +1,28 @@
+manim\_directive.ManimDirective
+===============================
+
+.. currentmodule:: manim_directive
+
+.. autoclass:: ManimDirective
+ :show-inheritance:
+ :members:
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+ :nosignatures:
+
+ ~ManimDirective.run
+
+
+ .. rubric:: Attributes
+
+ .. autosummary::
+
+ ~ManimDirective.final_argument_whitespace
+ ~ManimDirective.has_content
+ ~ManimDirective.option_spec
+ ~ManimDirective.optional_arguments
+ ~ManimDirective.required_arguments
+
\ No newline at end of file
diff --git a/docs/source/contributing/reference/manim_directive.rst b/docs/source/contributing/reference/manim_directive.rst
new file mode 100644
index 000000000..2b0269375
--- /dev/null
+++ b/docs/source/contributing/reference/manim_directive.rst
@@ -0,0 +1,44 @@
+manim\_directive
+================
+
+.. currentmodule:: manim_directive
+
+.. automodule:: manim_directive
+
+
+
+
+
+
+
+ .. rubric:: Classes
+
+ .. autosummary::
+ :toctree: .
+ :nosignatures:
+
+ ManimDirective
+
+ skip_manim_node
+
+
+
+
+
+
+ .. rubric:: Functions
+
+
+ .. autofunction:: depart
+ .. autofunction:: process_name_list
+ .. autofunction:: setup
+ .. autofunction:: visit
+
+
+
+
+
+
+
+
+
diff --git a/docs/source/contributing/reference/manim_directive.skip_manim_node.rst b/docs/source/contributing/reference/manim_directive.skip_manim_node.rst
new file mode 100644
index 000000000..447ed1b15
--- /dev/null
+++ b/docs/source/contributing/reference/manim_directive.skip_manim_node.rst
@@ -0,0 +1,32 @@
+manim\_directive.skip\_manim\_node
+==================================
+
+.. currentmodule:: manim_directive
+
+.. autoclass:: skip_manim_node
+ :show-inheritance:
+ :members:
+
+
+ .. rubric:: Methods
+
+ .. autosummary::
+ :nosignatures:
+
+
+
+ .. rubric:: Attributes
+
+ .. autosummary::
+
+ ~skip_manim_node.basic_attributes
+ ~skip_manim_node.child_text_separator
+ ~skip_manim_node.document
+ ~skip_manim_node.known_attributes
+ ~skip_manim_node.line
+ ~skip_manim_node.list_attributes
+ ~skip_manim_node.local_attributes
+ ~skip_manim_node.parent
+ ~skip_manim_node.source
+ ~skip_manim_node.tagname
+
\ No newline at end of file
diff --git a/docs/source/contributing/testing.rst b/docs/source/contributing/testing.rst
new file mode 100644
index 000000000..bcdfac1ae
--- /dev/null
+++ b/docs/source/contributing/testing.rst
@@ -0,0 +1,306 @@
+============
+Adding Tests
+============
+When adding a new feature, it should always be tested. Tests prevent
+manim from breaking at each new feature added by checking if any other
+feature has been broken and/or been unintentionally modified.
+
+How Manim Tests
+---------------
+
+To conduct our tests, we use ``pytest``. Running ``pytest`` in the root of
+the project will start the testing process, and will show if there is
+something wrong.
+
+Some useful pytest flags:
+- ``-x``, that will make pytest stop at the first fail,
+- ``-s``, that will make pytest display all the print messages (including those during scene generation, like DEBUG messages).
+- ``--skip_slow`` will skip the (arbitrarly) slow tests.
+- ``--show_diff`` will show a visual comparison in case an unit test is
+failing.
+
+How it Works
+~~~~~~~~~~~~
+
+At the moment there are three type of tests:
+
+#. Unit Tests:
+
+ Basically test for pretty much everything. For example, there a test for
+ ``Mobject``, that checks if it can be added to a Scene, etc ..
+
+#. Graphical unit tests:
+
+ Because ``manim`` is a video library, we tests frames. To do so, we take a
+ frame of control data for each feature and compare the last frame of the
+ feature rendered (in the form of a numpy array). If it matches, the tests
+ are successful. If one wants to visually see the what has changed, you can
+ use ``--show_diff`` flag along with ``pytest`` to be able to visualize
+ what is different.
+
+#. Videos format tests:
+
+ As Manim is a video library, we have to test videos as well. Unfortunalty,
+ we can't test directly video content as manim outputs videos that can
+ differ slightly from one system to another (for reasons related to
+ ffmpeg). As such, we just compare videos configuration values, exported in
+ .json.
+
+Architecture
+------------
+
+``manim/tests`` directory looks like this:
+
+::
+
+ .
+ ├── conftest.py
+ ├── control_data
+ │ ├── graphical_units_data
+ │ │ ├── creation
+ │ │ │ ├── DrawBorderThenFillTest.npy
+ │ │ │ ├── FadeInFromDownTest.npy
+ │ │ │ ├── FadeInFromLargeTest.npy
+ │ │ │ ├── FadeInFromTest.npy
+ │ │ │ ├── FadeInTest.npy
+ │ │ │ ├── ...
+ │ │ ├── geometry
+ │ │ │ ├── AnnularSectorTest.npy
+ │ │ │ ├── AnnulusTest.npy
+ │ │ │ ├── ArcBetweenPointsTest.npy
+ │ │ │ ├── ArcTest.npy
+ │ │ │ ├── CircleTest.npy
+ │ │ │ ├── CoordinatesTest.npy
+ │ │ │ ├── ...
+ │ │ ├── graph
+ │ │ │ ├── ...
+ | | | | ...
+ │ └── videos_data
+ │ ├── SquareToCircleWithDefaultValues.json
+ │ └── SquareToCircleWithlFlag.json
+ ├── helpers
+ │ ├── graphical_units.py
+ │ ├── __init__.py
+ │ └── video_utils.py
+ ├── __init__.py
+ ├── test_camera.py
+ ├── test_config.py
+ ├── test_container.py
+ ├── test_copy.py
+ ├── test_vectorized_mobject.py
+ ├── test_graphical_units
+ │ ├── conftest.py
+ │ ├── __init__.py
+ │ ├── test_creation.py
+ │ ├── test_geometry.py
+ │ ├── test_graph.py
+ │ ├── test_indication.py
+ │ ├── test_movements.py
+ │ ├── test_threed.py
+ │ ├── test_transform.py
+ │ └── test_updaters.py
+ ├── test_logging
+ │ ├── basic_scenes.py
+ │ ├── expected.txt
+ │ ├── testloggingconfig.cfg
+ │ └── test_logging.py
+ ├── test_scene_rendering
+ │ ├── conftest.py
+ │ ├── __init__.py
+ │ ├── simple_scenes.py
+ │ ├── standard_config.cfg
+ │ └── test_cli_flags.py
+ └── utils
+ ├── commands.py
+ ├── GraphicalUnitTester.py
+ ├── __init__.py
+ ├── testing_utils.py
+ └── video_tester.py
+ ...
+
+The Main Directories
+--------------------
+
+- ``control_data/``:
+
+ Here control data is saved. These are generally frames
+ that we expect to see. In ``control_data/graphical_units_data/`` are all the
+ .npz (represented the last frame) used in graphical unit tests videos, and in
+ ``control_data/videos_data/`` some .json used to check videos.
+
+- ``test_graphical_units/``:
+
+ For tests related to visual items that can appear in media
+
+- ``test_scene_rendering/``:
+
+ For tests that need to render a scene in a way or another. For example, CLI
+ flags (end-to-end tests).
+
+- ``utils/``:
+
+ Useful internal functions used by pytest to test.
+
+ .. Note:: fixtures are not contained here, they are in ``conftest.py``.
+
+- ``helpers/``:
+
+ Helper function for developers to setup graphical/video tests.
+
+Adding a New Test
+-----------------
+
+Unit Tests
+~~~~~~~~~~
+
+Pytest determines which functions are tests by searching for files whose
+names begin with "test\_" and then within those files for functions
+beginning with "test" or classes beginning with "Test". These kind of
+tests must be in ``tests/`` (e.g. ``tests/test_container.py``).
+
+Graphical Unit Test
+~~~~~~~~~~~~~~~~~~~
+
+The test must be written in the correct file and follow the structure
+of unit tests.
+
+For example, to test the ``Circle`` VMobject which resides in
+``manim/mobject/geometry.py``, add the CircleTest to
+``test/test_geometry.py``.
+
+In ``test_geometry.py``:
+
+.. code:: python
+
+ class CircleTest(Scene):
+ def construct(self):
+ circle = Circle()
+ self.play(Animation(circle))
+
+Scene names follow the syntax: ``<thing_to_test>Test``. In the example above,
+we are testing whether Circle properly shows up with the generic
+``Animation`` and not any specific animation.
+
+.. Note::
+
+ If the file already exists, just add to its content. The
+ ``Scene`` will be tested thanks to the ``GraphicalUnitTester`` that lives
+ in ``tests/utils/GraphicalUnitTester.py``. Import it with ``from
+ ..utils.GraphicalUnitTester import GraphicalUnitTester``.
+
+To test all the scenes in the module, we do the following:
+
+.. code:: python
+
+ @pytest.mark.parametrize("scene_to_test", get_scenes_to_test(__name__), indirect=False)
+ def test_scene(scene_to_test, tmpdir, show_diff):
+ GraphicalUnitTester(scene_to_test[1], MODULE_NAME, tmpdir).test(show_diff=show_diff)
+
+The first line is a `pytest decorator
+<https://docs.pytest.org/en/stable/parametrize.html>`_.
+It is used to run a test function several times with different
+parameters. Here, we pass in all the scenes as arguments.
+
+.. warning::
+ If you run pytest now, you will get a ``FileNotFound`` error. It's because
+ you haven't created control data for your test.
+
+Next, we'll want to create control data for ``CircleTest``. In
+``tests/template_generate_graphical_units_data.py``, there exist the
+function, ``set_test_scene``, for this purpose.
+
+It will looks like this :
+
+.. code:: python
+
+ class CircleTest(Scene):
+ def construct(self):
+ circle = Circle()
+ self.play(Animation(circle))
+
+ set_test_scene(CircleTest, "geometry")
+
+``set_test_scene`` takes two parameters : the scene to test, and the
+module name. It will automatically generate the control data at the
+right place (in this case,
+``tests/control_data/graphical_units_data/geometry/CircleTest.npz``).
+
+That's all there is to it. Please make sure to add the control data to git as
+soon as it is produced with ``git add <your-control-data.npz>`` but do NOT
+include changes to the template script in your pull request so that others
+may continue to use the template file
+(template\_generate\_graphical\_units\_data.py) will be still available for
+others.
+
+Videos tests
+~~~~~~~~~~~~
+
+To test videos generated, we use the decorator
+``tests.utils.videos_tester.video_comparison``:
+
+.. code:: python
+
+ @video_comparison(
+ "SquareToCircleWithlFlag.json", "videos/simple_scenes/480p15/SquareToCircle.mp4"
+ )
+ def test_basic_scene_l_flag(tmp_path, manim_cfg_file, simple_scenes_path):
+ scene_name = "SquareToCircle"
+ command = [
+ "python",
+ "-m",
+ "manim",
+ simple_scenes_path,
+ scene_name,
+ "-l",
+ "--media_dir",
+ str(tmp_path),
+ ]
+ out, err, exit_code = capture(command)
+ assert exit_code == 0, err
+
+.. Note:: ``assert exit*\ code == 0, err`` is used in case of the command fails
+to run. The decorator takes two arguments: json name and the path
+to where the video should be generated, starting from the ``medias/`` dir.
+
+Note the fixtures here:
+
+- tmp_path is a pytest fixture to get a tmp_path. Manim will output here, according to the flag ``--media_dir``.
+
+- ``manim_cfg_file`` fixture that return a path pointing to ``test_scene_rendering/standard_config.cfg``. It's just to shorten the code, in the case multiple tests need to use this cfg file.
+
+- ``simple_scenes_path`` same as above, except for ``test_scene_rendering/simple_scene.py``
+
+You have to generate a ``.json`` file first to be able to test your video. To
+do that, use ``helpers.save_control_data_from_video``.
+
+For instance, a test that will check if the l flag works properly will first
+require rendering a video using the -l flag from a scene. Then we will test
+(in this case, SquareToCircle), that lives in
+``test_scene_rendering/simple_scene.py``. Change directories to ``tests/``,
+create a file (e.g. ``create\_data.py``) that you will remove as soon as
+you're done. Then run:
+
+.. code:: python
+
+ save_control_data_from_video(<path-to-video>, "SquareToCircleWithlFlag.json").
+
+Running this will save
+``control_data/videos_data/SquareToCircleWithlFlag.json``, whoch will
+looks like this :
+
+.. code:: json
+
+ {
+ "name": "SquareToCircleWithlFlag",
+ "config": {
+ "codec_name": "h264",
+ "width": 854,
+ "height": 480,
+ "avg_frame_rate": "15/1",
+ "duration": "1.000000",
+ "nb_frames": "15"
+ }
+ }
+
+If you have any question don't hesitate to ask on `Discord
+<https://discord.gg/mMRrZQW>`_, in your pull request, or open an issue.
diff --git a/docs/source/installation/for_dev.rst b/docs/source/installation/for_dev.rst
index a62eb33ae..a1de70c54 100644
--- a/docs/source/installation/for_dev.rst
+++ b/docs/source/installation/for_dev.rst
@@ -4,11 +4,10 @@ Manim Installation For Developers
This documentation is for developers who want to contribute to ``ManimCommunity/manim``.
Thank you for your interest in contributing! Please see our documentation on
-:doc:`contributing` to take the necessary steps before installing Manim as a
+:doc:`../contributing` to take the necessary steps before installing Manim as a
developer. This documentation assumes you have already taken the necessary
steps to clone your fork.
-
.. warning::
If you have installed a non-developer version of manim, please uninstall
diff --git a/manim/mobject/geometry.py b/manim/mobject/geometry.py
index 2ad905b30..36e09b09b 100644
--- a/manim/mobject/geometry.py
+++ b/manim/mobject/geometry.py
@@ -655,14 +655,14 @@ class LabeledDot(Dot):
class Ellipse(Circle):
"""A circular shape; oval, circle.
- Parameters
- ----------
- width : :class:`float`, optional
- The horizontal width of the ellipse.
- height : :class:`float`, optional
- The vertical height of the ellipse.
- kwargs : Any
- Additional arguments to be passed to :class:`Circle`
+ Parameters
+ ----------
+ width : :class:`float`, optional
+ The horizontal width of the ellipse.
+ height : :class:`float`, optional
+ The vertical height of the ellipse.
+ kwargs : Any
+ Additional arguments to be passed to :class:`Circle`
Examples
--------