Update tox

Author: jgujerry

tox/README.md

@@ -35,7 +35,109 @@ $ tox --help
 
 ## How to use it?
 
-?
+
+`tox` is an environment orchestrator, it needs `tox.ini` configuration file to define what tools required to
+setup and execute on your project's test environment. 
+
+#### 1. A minimal configuration file
+
+Create `tox.ini` with the following configuration:
+```ini
+[tox]
+skipsdist = true
+```
+
+Then run `tox` command:
+```bash
+$ tox
+ py: OK (0.15 seconds)
+ congratulations :) (0.20 seconds)
+```
+
+What's happened? Under the work directory, a `.tox` directory was created with the following contents:
+
+```bash
+.tox
+└── py
+ ├── bin
+ │   ├── activate
+ │   ├── activate.csh
+ │   ├── activate.fish
+ │   ├── activate.nu
+ │   ├── activate.ps1
+ │   ├── activate_this.py
+ │   ├── pip
+ │   ├── pip3
+ │   ├── pip-3.10
+ │   ├── pip3.10
+ │   ├── python -> /usr/bin/python3
+ │   ├── python3 -> python
+ │   ├── python3.10 -> python
+ │   ├── wheel
+ │   ├── wheel3
+ │   ├── wheel-3.10
+ │   └── wheel3.10
+ ├── lib
+ │   └── python3.10
+ ├── pyvenv.cfg
+ └── tmp
+
+5 directories, 18 files
+```
+
+You can see **py** is the default environment created by tox, and py version is what default in your machine.
+
+#### 2. Define your environment list
+
+You can control the environment creation by specifying the `env_list` or `envlist` option
+
+```ini
+[tox]
+skipsdist = true
+env_list = py310,py311,py312
+```
+
+Then run command `$tox` again, you can see these Python environments created under `.tox` directory,
+
+```bash
+.tox
+├── py310
+│   ├── bin
+│   ├── lib
+│   ├── pyvenv.cfg
+│   └── tmp
+├── py311
+│   ├── bin
+│   ├── lib
+│   ├── pyvenv.cfg
+│   └── tmp
+└── py312
+ ├── bin
+ ├── lib
+ ├── pyvenv.cfg
+ └── tmp
+
+12 directories, 3 files
+```
+
+What's about if you specify a Python version that does not exist on your system? For example, if I specify `py39` in `env_list` and Python 3.9 
+is not installed on my machine, then `tox` would skip it and show the following information:
+
+```bash
+py39: skipped because could not find python interpreter with spec(s): py39
+py39: SKIP ⚠ in 0.02 seconds
+```
+
+#### 3. More on Configuration
+
+There are two types of configurations: core settings `[tox]`, and per-run environment settings `[testenv]` and `[testenv:<envname>]`.
+
+Except for the `tox.ini` configuration, `tox` supports `pyproject.toml` and `setup.cfg` as well. `tox` supports three configuration locations
+prioritized in the following order:
+ 1. `tox.ini`
+ 2. `pyproject.toml`
+ 3. `setup.cfg`
+
 
 For more information about `tox`, please refer to the [official documentation](https://tox.wiki/).
 

tox/tox.ini

@@ -0,0 +1,3 @@
+[tox]
+skipsdist = true
+env_list = py39,py310,py311,py312