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

CorvidCanine · naveen521kk · web-flow · commit 95ff9f89d678 · 2020-09-05T11:17:36.000-04:00
* Move bug report guide to own page, rewrite contributing guide, add a troubleshooting solution

* Apply suggestions from code review of contributing guide rewrite

Co-authored-by: Naveen M K &lt;naveen@syrusdark.website&gt;

* Change contributing guide to checkout master

Instead of saying how to checkout any branch, change contributing.md to say how to checkout the master branch specifically.

Co-authored-by: Naveen M K &lt;naveen@syrusdark.website&gt;
diff --git 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 (`git@github.com:<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
@@ -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
@@ -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
@@ -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
@@ -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.
