make development setup instructions more clear

Our dev.sh/dev.ps1 scripts feel like an unnecessary layer of abstraction.
The revised docs make the install process transparent to experienced users,
and can also be easily reused for other projects (hi, pdoc!).

CONTRIBUTING.md

@@ -14,32 +14,49 @@ forward, please consider contributing in the following areas:
 
 ## Development Setup
 
-To get started hacking on mitmproxy, please install a recent version of Python (we require at least Python 3.8). The
+To get started hacking on mitmproxy, please install a recent version of Python (we require at least Python 3.8). 
-following commands should work on your system:
+Then, do the following:
 
+##### Linux / macOS
 ```shell
+# 1) Verify that these commands work:
 python3 --version
 python3 -m pip --help
 python3 -m venv --help
-```
+# 2) Install:
-
-If all of this run successfully, do the following:
-
-```shell
 git clone https://github.com/mitmproxy/mitmproxy.git
 cd mitmproxy
-./dev.sh  # "powershell .\dev.ps1" on Windows
+python3 -m venv venv
+venv/bin/pip install -e .[dev]
 ```
 
-The *dev* script will create a [virtualenv](https://virtualenv.pypa.io/) environment in a directory called "venv" and
+##### Windows
-install all mandatory and optional dependencies into it. The primary mitmproxy components are installed as "editable",
+```shell
-so any changes to the source in the repository will be reflected live in the virtualenv.
+# 1) Verify that this command works:
+python --version
+# 2) Install:
+git clone https://github.com/mitmproxy/mitmproxy.git
+cd mitmproxy
+python -m venv venv
+venv\Scripts\pip install -e .[dev]
+```
 
-The main executables for the project - `mitmdump`, `mitmproxy`, and `mitmweb` - are all created within the virtualenv.
+This will clone mitmproxy's source code into a directory with the same name,
+and then create an isolated Python environment (a [virtualenv](https://virtualenv.pypa.io/)) into which all dependencies are installed.
+Mitmproxy itself is installed as "editable", so any changes to the source in the repository will be reflected live in the virtualenv.
+
+The main executables for the project – `mitmdump`, `mitmproxy`, and `mitmweb` – are all created within the virtualenv.
 After activating the virtualenv, they will be on your $PATH, and you can run them like any other command:
 
+##### Linux / macOS
 ```shell
-. venv/bin/activate  # "venv\Scripts\activate" on Windows
+source venv/bin/activate
+mitmdump --version
+```
+
+##### Windows
+```shell
+venv\Scripts\activate
 mitmdump --version
 ```
 
@@ -52,41 +69,30 @@ basic test suite with [tox](https://tox.readthedocs.io/):
 tox -e py      # runs Python tests
 ```
 
-Our CI system has additional tox environments that are run on every pull request and branch on GitHub.
+Our CI system has additional tox environments that are run on every pull request (see [tox.ini](./tox.ini)).
 
-For speedier testing, we recommend you run [pytest](http://pytest.org/) directly on individual test files or folders:
+For speedier testing, you can also run [pytest](http://pytest.org/) directly on individual test files or folders:
 
 ```shell
 cd test/mitmproxy/addons
 pytest --cov mitmproxy.addons.anticache --cov-report term-missing --looponfail test_anticache.py
 ```
 
-Pytest does not check the code style, so you want to run `tox -e flake8` and `tox -e mypy` again before committing.
-
 Please ensure that all patches are accompanied by matching changes in the test suite. The project tries to maintain 100%
 test coverage and enforces this strictly for some parts of the codebase.
 
-## Documentation
+### Code Style
 
-The following tools are required to build the mitmproxy docs:
+Keeping to a consistent code style throughout the project makes it easier to contribute and collaborate.
 
-- [Hugo](https://gohugo.io/) (the extended version `hugo_extended` is required)
+We enforce the following check for all PRs:
-- [modd](https://github.com/cortesi/modd)
-
-```shell
-cd docs
-modd
-```
-
-## Code Style
-
-Keeping to a consistent code style throughout the project makes it easier to contribute and collaborate. Please stick to
-the guidelines in [PEP8](https://www.python.org/dev/peps/pep-0008) unless there's a good reason not to.
-
-This is automatically enforced on every PR. If we detect a linting error, the PR checks will fail and block merging. You
-can run our lint checks yourself with the following commands:
 
 ```shell
 tox -e flake8
-tox -e mypy    # checks static types
 ```
+
+If a linting error is detected, the automated pull request checks will fail and block merging.
+
+## Documentation
+
+Please check [docs/README.md](./docs/README.md) for instructions.

dev.ps1

@@ -1,15 +0,0 @@
-$ErrorActionPreference = "Stop"
-
-python -m venv .\venv --copies
-& .\venv\Scripts\activate.ps1
-
-python -m pip install --disable-pip-version-check -U pip
-cmd /c "pip install -r requirements.txt 2>&1"
-
-echo @"
-
-  * Created virtualenv environment in .\venv.
-  * Installed all dependencies into the virtualenv.
-  * Activated virtualenv environment.
-
-"@

dev.sh

@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-
-set -o errexit
-set -o pipefail
-set -o nounset
-set -o xtrace
-
-echo "Creating dev environment in ./venv..."
-
-python3 -m venv venv
-. venv/bin/activate
-pip3 install -U pip setuptools
-pip3 install -r requirements.txt
-
-echo ""
-echo "  * Created virtualenv environment in ./venv."
-echo "  * Installed all dependencies into the virtualenv."
-echo "  * You can now activate the $(python3 --version) virtualenv with this command: \`. venv/bin/activate\`"

docs/README.md

@@ -17,6 +17,6 @@ Now you can run `hugo server -D` in ./src.
 
 This is required to modify CSS files.
 
- 1. Install hugo extended version.
+ 1. Install "extended" hugo version.
 
 You can now run `modd` in this directory instead of running hugo directly.