Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Rewrite contributing guide and add two troubleshooting soulutions (#384)

CorvidCanine95ff9f89d678
diff --git a/docs/source/contributing.md b/docs/source/contributing.md
index 7e44f2461..2d7a4d11e 100644
--- a/docs/source/contributing.md
+++ b/docs/source/contributing.md
@@ -4,71 +4,36 @@ Thank you for 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. Manim is a free open source software for mathematical
animations, and as such we welcome **everyone** who is interested in
-mathematics, pedagogy, computer animations, open source, software development,
+mathematics, pedagogy, computer animations, open-source, software development,
and beyond. Manim accepts contributions of many kinds, detailed below.
-
-## Reporting bugs
-
-One of the best ways of contributing to Manim is by reporting bugs. If you
-have encountered something that you believe is a bug, please follow these
-steps:
-
-1. First of all, make sure you are running the latest version of manim. If
- not, update your version and try again.
-
-2. Make sure to search for other users who may have had similar issues in the
- past. Search the repository's issues page (don't forget to search closed
- issues), bring it up on Discord, use sites like StackOverflow, and exercise
- your best Google practices. If you can't find anything helpful, then go to
- the next step.
-
-3. Make sure you can reproduce the issue, i.e. that you have some code that
- illustrates the bug **every time** (or at least most of the time) it is
- executed.
-
-4. Make sure to clarify what behavior you expected, and how the actual behavior
- differs from your expectation.
-
-5. Make sure to gather information about your environment, such as your
- operating system, python version, and any stack traces that the code may
- have generated (if applicable).
-
-4. Please open an issue only after you have gathered this information. When
- submitting an issue, make sure to follow the template (this is the default
- text you are shown when first opening the 'New Issue' page). A community
- member will (hopefully) respond and start a conversation to address the
- issue.
-
-7. Please give the community a reasonable amount of time before asking again,
- or insisting on your issue. Keep in mind that everyone is a volunteer. If
- you wait for a reasonable amount of time and you receive no response, feel
- free to ask again.
-
-
-## Contributing code
-
Many ways of contributing will involve writing, reading, testing, or
refactoring code. As our repository is a Fork of [Manim by
3b1b](https://github.com/3b1b/manim), contributing in this way can be a bit
confusing. Here is a short guide on how to do it.
-1. First, make a fork of this repository. This creates your own copy of the
- whole codebase on GitHub.
+1. Make a fork of this repository on Github.
+
+ You will need an account with Github. This will allow you to make pull requests (PR)
+ to the ManimCommunity repo later on.
-2. Clone the repository you forked using the command below (bash/zsh).
+2. Clone your fork.
+ You can clone your Github fork by running:
```sh
git clone <your-fork-url>
cd manim
```
- Note: do not `git clone` the original ManimCommunity repository. You must
+ GitHub will provide both a SSH (`[email protected]:<your-username>/manim.git`) and
+ HTTPS (`https://github.com/<your-username>/manim.git`) URL for cloning the repo.
+ You can use whichever one you are setup for.
+
+ Note: Do not `git clone` the original ManimCommunity repository. You must
clone your own fork. After this step, there are three different
repositories to keep track of: the original ManimCommunity repo, your own
fork of it, and your local repository.
-3. You have to make `git` be aware of the two remote repositories, by entering
- the commands below.
+3. Make `git` aware of the ManimCommunity repo.
```sh
git remote add upstream https://github.com/ManimCommunity/manim.git
@@ -79,85 +44,118 @@ confusing. Here is a short guide on how to do it.
(referred to as 'origin') as well as the main ManimCommunity repository
(referred to as 'upstream').
-4. Choose the correct branch for your changes. If you are working on a branch
- that already exists on the main repository, you can execute
+4. Choose the branch for your changes.
+
+ To work on the ManimCommunity master branch, you can change to it with:
```sh
- git checkout -b <branch-name> upstream/master
+ git checkout -b master upstream/master
```
If you are starting a new branch, execute
```sh
git checkout -b <new_branch-name>
```
+5. Install manim.
+
+ Install the required packages and manim itself:
+ ```sh
+ pip install -e .
+ ```
+
+ Manim has other requirements that you will need to install,
+ explained in the [Installation](installation) instructions.
+
- You can now make any changes to your local repository, add them, and commit
+6. Write some awesome code!
+
+ You're ready to make changes in your local repository, add them, and commit
them.
-5. To make your changes visible in your GitHub fork, instead of typing in `git
- push` as usual, you need to enter the command below.
+7. Update docstrings and documentation.
- ```sh
- git push -u origin <branch-name>
- ```
+ You should 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.
+
+ You must check that the command `make doctest`, executed from the `docs/` folder
+ terminates without problems after your changes.
+
+8. Add/update tests.
+
+ Depending on the changes you are making you will need to update or add new tests.
+ If you have added a new feature or bug fix, it is strongly
+ preferred that you include tests with your PR.
+ Please check out the [Wiki Entry for Testing](https://github.com/ManimCommunity/manim/wiki/Testing)
+ to learn how our tests work.
- Doing so creates a new branch with the updated contents of your fork on
- GitHub (the 'origin').
+9. Check for merge conflicts.
-6. If you want your changes to be incorporated to the main ManimCommunity
+ If you want your changes to be incorporated to the main ManimCommunity
repository, you need to make sure that there are no merge conflicts between
- the current upstream/master and the changes you are trying to make. For
- this purpose, please execute `git pull upstream master` before you push
- changes to your fork. If this generates merge conflicts, make sure to
- resolve them before submitting a PR.
+ the current upstream/master and the changes you are trying to make. To do this
+ you will need to update your local repo with any changes that have
+ been made to the ManimCommunity repo while you've been working with
+ `git pull upstream master`.
+ This will probably generate merge conflicts that you will need to resolve.
-7. Further, make sure that you run the tests locally and that they all pass
- before submitting a PR. You can run the tests locally by executing `pytest`
- from the main `manim/` folder (do not execute pytest from the code folder
- `manim/manim`).
+10. Run the `black` autoformatter.
-8. Finally, make sure to use the `black` autoformatter before submitting a PR.
- You can execute it by running `black <your_file>`. This will make changes
- to your code, and you will need to add/commit those changes.
+ You can run black on a file or directory with `black <file_or_directory>` to
+ format your code to the same standard as the rest of ManimCommunity.
+ This will make changes to your code, so you will need to add/commit those changes
+ if you commit before running it. Most python IDE/text editors have packages for
+ running black after every save if you would like to keep formatting consistent while
+ you work.
-9. To request the ManimCommunity dev team to incorporate the changes in your
- fork into the main repository, you can make a Pull Request to the Manim
- Community repo from your fork. Make sure to select `ManimCommunity/manim`
- instead of `3b1b/manim` as the `base repository` and your fork and branch as
- `head repository` - see the picture below.
+11. Run `pytest`.
- ![pull-requests-example-manim-community](./_static/pull-requests.PNG)
+ You can check that everything is still working properly after your modifications
+ with `pytest`. Make sure that you run the tests locally and that they all pass
+ before submitting a PR. `pytest` should be run from the main `manim/`
+ folder (Not the `manim/manim` subfolder).
- Once again, please make sure to follow the template (this is the default
+12. Update your GitHub fork with local changes.
+
+ To make your changes visible in your GitHub fork, instead of typing in `git
+ push` as usual, you need to enter the command below.
+
+ ```sh
+ git push -u origin <branch-name>
+ ```
+
+ Doing so creates a new branch with the updated contents of your fork on
+ GitHub (the 'origin').
+
+13. Make a Pull Request on Github.
+
+ To request the ManimCommunity dev team to incorporate the changes in your
+ fork into the main repository, you can make a Pull Request to the Manim
+ Community repo from your fork. Make sure to select `ManimCommunity/manim`
+ instead of `3b1b/manim` as the `base repository` and your fork and branch as
+ `head repository` - see the screenshot below.
+
+ ![pull-requests-example-manim-community](./_static/pull-requests.PNG)
+
+ Please make sure you follow the template (this is the default
text you are shown when first opening the 'New Pull Request' page)
-10. Once a PR is submitted, it will require at least two approving code
- reviews from community developers, as well as all tests passing. It is
- very likely that you will be asked to edit or modify your PR in one way or
+14. Wait for feedback and make any requested changes.
+
+ Thank you for contributing! Once your PR is submitted, it will require at least
+ two approving code reviews from community developers. It will also be automatically
+ tested. These tests must all pass for the PR to be merged.
+ 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 dev community wants to merge your changes!
-Note: before submitting a PR please make sure that you update the docstrings of
-any methods, classes, or modules that your PR modifies, if necessary.
-
-Note: if you are contributing new features or bug fixes, it is strongly
-preferred that you include tests that accompany them in your PR. For this
-purpose, you can create a new file under the `tests/` folder and make sure that
-your new tests pass before submitting your PR. Please check out the [Wiki Entry
-for Testing](https://github.com/ManimCommunity/manim/wiki/Testing) to learn
-more about how our tests work.
-
-Note: if you are contributing documentation, you must also make sure that the
-command `make doctest`, executed from the `docs/` folder terminates without
-problems. Please check out the [Wiki Entry for
-Documentation](https://github.com/ManimCommunity/manim/wiki//Documentation-guidelines-(WIP))
-to learn more about how we prefer our code documented.
-
-Note: In order to open a PR, you do not need to have everything
-(documentation/tests) complete and ready to go. However, the more complete
-your PR is, the easier it will be for community devs to review it, and the
-quicker it will be merged. If you open a PR that is still under development
-and you want a quick overview or start some discussion about planned
-yet-to-be-implemented changes, please mark your PR as a draft.
+ Note: To open a PR, you do not need to have everything
+ (documentation/tests) complete and ready to go. However, the more complete
+ your PR is, the easier it will be for community devs to review it, and the
+ quicker it will be merged. If you open a PR that is still under development
+ and you want a quick overview or start some discussion about planned
+ yet-to-be-implemented changes, please mark your PR as a draft.
## Other guidelines
diff --git a/docs/source/index.rst b/docs/source/index.rst
index cadc32677..8c4524b7b 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -24,6 +24,7 @@ information here will make it easier for newcomers to get started using
reference
examples
tutorials
+ reporting_bugs
contributing
Navigation
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index cc407cad1..3195f6e0b 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -51,6 +51,9 @@ cloned this repo, run the following:
.. code-block:: bash
python3 -m pip install -r requirements.txt
+ python3 -m pip install -e .
+
+Please see :doc:`contributing` for more details about contributing to Manim.
.. warning::
If you want to contribute to ``manim-community`` and have cloned the
diff --git a/docs/source/installation/troubleshooting.rst b/docs/source/installation/troubleshooting.rst
index 727c671a6..356008bac 100644
--- a/docs/source/installation/troubleshooting.rst
+++ b/docs/source/installation/troubleshooting.rst
@@ -2,3 +2,13 @@ Troubleshooting
===============
List of known installation problems.
+
+Some letters are missing from TextMobject/TexMobject output?
+------------------------------------------------------------
+
+If you have recently installed TeX you may need to build the fonts it
+uses. Which can be done by running:
+
+.. code-block:: bash
+
+ fmtutil -sys --all
diff --git a/docs/source/reporting_bugs.rst b/docs/source/reporting_bugs.rst
new file mode 100644
index 000000000..38db80a00
--- /dev/null
+++ b/docs/source/reporting_bugs.rst
@@ -0,0 +1,37 @@
+Reporting bugs
+===============
+
+One of the best ways of contributing to Manim is by reporting bugs. If you
+have encountered something that you believe is a bug, please follow these
+steps:
+
+1. First of all, make sure you are running the latest version of manim. If
+ not, update your version and try again.
+
+2. Search for other users who may have had similar issues in the
+ past. Search the repository's `issues page <https://github.com/ManimCommunity/manim/issues>`_ (don't forget to search closed
+ issues), bring it up on out `Discord server <https://discord.gg/mMRrZQW>`_, use sites like StackOverflow, and exercise
+ your best Google practices. If you can't find anything helpful, then go to
+ the next step.
+
+3. Can reproduce the issue, i.e. that you have some code that
+ illustrates the bug **every time** (or at least most of the time) it is
+ executed.
+
+4. Clarify what behavior you expected, and how the actual behavior
+ differs from your expectation.
+
+5. Gather information about your environment, such as your
+ operating system, python version, and any stack traces that the code may
+ have generated (if applicable).
+
+4. Please open an issue only after you have gathered this information. When
+ submitting an issue, make sure to follow the template (this is the default
+ text you are shown when first opening the 'New Issue' page). A community
+ member will (hopefully) respond and start a conversation to address the
+ issue.
+
+7. Please give the community a reasonable amount of time before asking again,
+ or insisting on your issue. Keep in mind that everyone is a volunteer. If
+ you wait for a reasonable amount of time and you receive no response, feel
+ free to ask again.