Update: Contributing guide with respect to #1358 (#1389)

* Update: Contributing guide with respect to #1358

* Fix: Add line on manually running pre-commit

* Add: Line for `isort` in contributing guide

* Fix: uncomment `make examples` in overview

Author: eddiebergman

CONTRIBUTING.md

@@ -87,7 +87,11 @@ Following that we'll tell you about how you can test your changes locally and th
         Fortunately, you can check out [pyenv](https://github.com/pyenv/pyenv) which lets you switch between Python versions on the fly!
 
 *   Now that we have a virtual environment, it's time to install all the dependencies into it.
+    We've provided a simple `make` command to help do this.
     ```bash
+    make install-dev
+
+    # Manually
     pip install -e .[test,examples,doc]
 
     # If you're using shells other than bash you'll need to use
@@ -101,6 +105,8 @@ Following that we'll tell you about how you can test your changes locally and th
         You can check out what these are in the `setup.py` file.
     *   If you're new to virtual environments, after performing all this, it's a great time to check out what actually exists in the `my-virtual-env` folder.
 
+* You can check out some functionality we have captured in a `Makefile` by running `make help`
+
 *   Now it's time to make some changes, whether it be for [documentation](#documentation), a [bug fix](#bug-fixes) or a new [features](#features).
 
 ## Making Changes
@@ -234,23 +240,18 @@ Lastly, if the feature really is a game changer or you're very proud of it, cons
 
 *   Now we are going to use [sphinx](https://www.sphinx-doc.org/en/master/) to generate all the documentation and make sure there are no issues.
     ```bash
-    cd doc
-    make html
+    make doc
     ```
     *   If you're unfamiliar with sphinx, it's a documentation generator which can read comments and docstrings from within the code and generate html documentation.
-    *   We also use sphinx-gallery which can take python files (such as those in the `examples` folder) and run them, creating html which shows the code and the output it generates.
-        Unfortunately this can take quite some time but you should only have to run this once.
-    *   If you need to quickly check something, you can run `make html-noexamples` to prevent sphinx from running the examples.
-    ```bash
-    cd doc
-    make html-noexamples
-    ```
-    *   Sphinx also has a command `linkcheck` for making sure all the links correctly go to some destination.
+    *   If you've added documentation, we also has a command `linkcheck` for making sure all the links correctly go to some destination.
         This helps tests for dead links or accidental typos.
     ```bash
-    cd doc
     make linkcheck
     ```
+    *   We also use sphinx-gallery which can take python files (such as those in the `examples` folder) and run them, creating html which shows the code and the output it generates.
+    ```bash
+    make examples
+    ```
     *   To view the documentation itself, make sure it is built with the above commands and then open `doc/build/html/index.html` with your favourite browser:
     ```bash
     # Firefox
@@ -261,19 +262,33 @@ Lastly, if the feature really is a game changer or you're very proud of it, cons
     ```
 
 *   Once you've made all your changes and all the tests pass successfully, we need to make sure that the code fits a certain format and that the [typing](https://docs.python.org/3/library/typing.html) is correct.
-    To do this, we use a tool call `pre-commit` which runs `flake8`, a code checker and `mypy`, a static type checker against the code.
+    * Formatting and import sorting can helps keep things uniform across all coding styles. We use `black` and `isort` to do this for us. To automatically run these formatters across the code base, just run the following command:
     ```bash
-    pip install pre-commit
-    pre-commit run --all-files
+    make format
     ```
-    *   The reason we use a code standard like `flake8` is to make sure that when we review code:
-        *   There are no extra blank spaces and blank lines.
-        *   Lines don't end up too long
-        *   Code from multiple source keeps a similar appearance.
-    *   We perform static type checking with `mypy` as this can remove a majority of bugs, before a test is even run.
-        It points out programmer errors and is what makes compiled languages so safe.
+    * To then check for other issues with `mypy`, `flake8` and `pydocstyle`, run
+    ```bash
+    make check
+    ```
+    * To do this checking automatically, we use `pre-commit` which if you already installed everything with `make install-dev` then this has been done for you.
+    This will happen every time you make a commit and warn you of any issues.
+    Otherwise you can run the following to install pre-commit.
+    ```bash
+    pre-commit install
+    ```
+    * To run `pre-commit` manually:
+    ```bash
+    pre-commit run --al-files
+    ```
+    *   The reason we use tools like `flake8`, `mypy`, `black`, `isort` and `pydocstyle` is to make sure that when we review code:
+        *   There are no extra blank spaces and blank lines. (`flake8`, `black`)
+        *   Lines don't end up too long. (`flake8`, `black`)
+        *   Code from multiple source keeps a similar appearance. (`black`)
+        *   Importing things is consistently ordered. (`isort`)
+        *   Functions are type annotated and correct with static type checking. (`mypy`)
+        * Function and classes have docstrings. (`pydocstyle`)
         If you are new to Python types, or stuck with how something should be 'typed', please feel free to push the pull request in the following steps and we should be able to help you out.
-    * If interested, the configuration for `pre-commit` can be found in `.pre-commit-config.yaml`
+    * If interested, the configuration for `pre-commit` can be found in `.pre-commit-config.yaml` with the other tools mainly being configured in `pyproject.toml` and `.flake8`.
 
 
 ## Creating the PR
@@ -341,6 +356,7 @@ Lastly, if the feature really is a game changer or you're very proud of it, cons
 
 # Pull Request Overview
 * Create a [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the [automl/auto-sklearn](https://github.com/automl/auto-sklearn) git repo
+* Check out what's available by running `make help`.
 * Clone your own fork and create a new branch from the branch to work on
     ```bash
     git clone [email protected]:your-username/auto-sklearn.git
@@ -355,15 +371,24 @@ Lastly, if the feature really is a game changer or you're very proud of it, cons
     python -m venv my-virtual-env
     source my-virtual-env/bin/activate
 
-    pip install -e .[test,docs,examples] # zsh users need quotes ".[test,...]"
+    make install-dev
+    # pip install -e ".[test,docs,examples]" # To manually install things
 
     # Edit files...
 
+    # Format code
+    make format
+
+    # Check for any issues
+    make check
+
+    # ... fix any issues
+
     # If you changed documentation:
-    # This will generate all documentation, run examples and check links
-    cd doc
-    make html
+    # This will generate all documentation and check links
+    make doc
     make linkcheck
+    make examples  # mainly needed if you modified some examples
 
     # ... fix any issues
 
@@ -373,8 +398,8 @@ Lastly, if the feature really is a game changer or you're very proud of it, cons
 
     # ... fix any issues
 
-    # Use pre-commit for style and typing checks
-    pip install pre-commit
+    # If you want to run pre-commit, the formatting checks we run on github
+    pre-commit install
     pre-commit run --all-files
 
     # ... fix any issues