docs(workflow): Overhaul linting

Author: tony

docs/contributing/workflow.md

@@ -6,18 +6,24 @@
 
 [poetry] is a required package to develop.
 
+```console
+$ git clone https://github.com/vcs-python/libvcs.git
 ```
-git clone https://github.com/vcs-python/libvcs.git
-cd libvcs
-poetry install -E "docs test coverage lint format"
+
+```console
+$ cd libvcs
+```
+
+```console
+$ poetry install -E "docs test coverage lint format"
 ```
 
 Makefile commands prefixed with `watch_` will watch files and rerun.
 
 ## Tests
 
-```
-poetry run py.test
+```console
+$ poetry run py.test
 ```
 
 Helpers: `make test` Rerun tests on file change: `make watch_test` (requires [entr(1)])
@@ -43,14 +49,105 @@ Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
 Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a `make(1)` with
 `-J` support, e.g. GNU Make)
 
-## Formatting / Linting
+## Formatting
 
-The project uses [black] and [isort] (one after the other) and runs [flake8] and [mypy] via CI. See
-the configuration in `pyproject.toml` and `setup.cfg`:
+The project uses [black] and [isort] (one after the other). Configurations are in `pyproject.toml`
+and `setup.cfg`:
 
 - `make black isort`: Run `black` first, then `isort` to handle import nuances
-- `make flake8`, to watch (requires `entr(1)`): `make watch_flake8`
-- `make mypy`, to watch (requires `entr(1)`): `make watch_mypy`
+
+## Linting
+
+[flake8] and [mypy] run via CI in our GitHub Actions. See the configuration in `pyproject.toml` and
+`setup.cfg`.
+
+### flake8
+
+[flake8] provides fast, reliable, barebones styling and linting.
+
+````{tab} Command
+
+poetry:
+
+```console
+$ poetry run flake8
+```
+
+If you setup manually:
+
+```console
+$ flake8
+```
+
+````
+
+````{tab} make
+
+```console
+$ make flake8
+```
+
+````
+
+````{tab} Watch
+
+```console
+$ make watch_flake8
+```
+
+requires [`entr(1)`].
+
+````
+
+````{tab} Configuration
+
+See `[flake8]` in setup.cfg.
+
+```{literalinclude} ../../setup.cfg
+:language: ini
+:start-at: "[flake8]"
+:end-before: "[isort]"
+
+```
+
+````
+
+### mypy
+
+[mypy] is used for static type checking.
+
+````{tab} Command
+
+poetry:
+
+```console
+$ poetry run mypy .
+```
+
+If you setup manually:
+
+```console
+$ mypy .
+```
+
+````
+
+````{tab} make
+
+```console
+$ make mypy
+```
+
+````
+
+````{tab} Watch
+
+```console
+$ make watch_mypy
+```
+
+requires [`entr(1)`].
+````
 
 ## Releasing
 
@@ -68,6 +165,7 @@ Update `__version__` in `__about__.py` and `pyproject.toml`::
 
 [poetry]: https://python-poetry.org/
 [entr(1)]: http://eradman.com/entrproject/
+[`entr(1)`]: http://eradman.com/entrproject/
 [black]: https://github.com/psf/black
 [isort]: https://pypi.org/project/isort/
 [flake8]: https://flake8.pycqa.org/