docs: Update hatch guidance (vega#3461)

* docs: Update references to `hatch` commands

These now use the dedicated `hatch-test` environment https://hatch.pypa.io/latest/tutorials/testing/overview/

* docs: adds two testing sub-sections in `CONTRIBUTING.md`

Related:
- vega#3452 (comment)
- vega#3452 (comment)

* docs: fix missing closing parenthesis

CONTRIBUTING.md

@@ -56,7 +56,11 @@ With this branch checked-out, make the desired changes to the package.
 A large part of Altair's code base is automatically generated.
 After you have made your manual changes,
 make sure to run the following to see if there are any changes
-to the automatically generated files: `python tools/generate_schema_wrapper.py`.
+to the automatically generated files: 
+
+```bash
+hatch run generate-schema-wrapper
+```
 
 For information on how to update the Vega-Lite version that Altair uses,
 please read [the maintainers' notes](NOTES_FOR_MAINTAINERS.md).
@@ -67,8 +71,8 @@ Before suggesting your contributing your changing to the main Altair repository,
 it is recommended that you run the Altair test suite,
 which includes a number of tests to validate the correctness of your code:
 
-```cmd
-hatch run test
+```bash
+hatch test
 ```
 
 
@@ -78,6 +82,26 @@ This also runs the [`ruff`](https://ruff.rs/) linter and formatter as well as [`
 Study the output of any failed tests and try to fix the issues
 before proceeding to the next section.
 
+#### Failures on specific python version(s)
+By default, `hatch test` will run the test suite against the currently active python version. Two useful variants for debugging failures that only appear *after* you've submitted your PR:
+
+```bash
+# Test all environments in the matrix
+hatch test --all
+# The Python versions to test
+hatch test --python 3.8
+```
+
+See [hatch test](https://hatch.pypa.io/latest/cli/reference/#hatch-test) docs for other options.
+
+#### Changes to `__all__`
+If `test_completeness_of__all__` fails, you may need to run:
+
+```bash
+hatch run update-init-file
+```
+However, this test usually indicates *unintentional* addition(s) to the top-level `alt.` namespace that will need resolving first.
+
 ### Creating a Pull Request
 
 When you are happy with your changes, you can commit them to your branch by running
@@ -187,7 +211,7 @@ The specific commands for each step depend on your operating system.
 Make sure you execute the following commands from the root dir of altair and have [`hatch`](https://hatch.pypa.io/) installed in your local environment.
 
 - For MacOS and Linux, run the following commands in your terminal:
-```cmd
+```bash
 hatch run doc:clean-all
 hatch run doc:build-html
 hatch run doc:serve

NOTES_FOR_MAINTAINERS.md

@@ -10,7 +10,7 @@ All the files within these directories are created automatically by running
 the following script from the root of the repository:
 
 ```bash
-$ hatch run python tools/generate_schema_wrapper.py
+hatch run generate-schema-wrapper
 ```
 
 This script does a couple things:
@@ -36,12 +36,14 @@ changing the ``SCHEMA_VERSION`` definition within
 This will update all of the automatically-generated files in the ``schema``
 directory for each version, but please note that it will *not* update other
 pieces (for example, the core of the Altair API, including methods and
-doc strings within ``altair/vegalite/v5/api.py``.
+doc strings within ``altair/vegalite/v5/api.py``).
 These additional methods have fairly good test coverage, so running the test
 suite should identify any inconsistencies:
+
+```bash
+hatch test
 ```
-hatch run test
-```
+
 Generally, minor version updates (e.g. Vega-Lite 2.3->2.4) have been relatively
 painless, maybe requiring the addition of a few chart methods or modification
 of some docstrings.

README.md

@@ -117,8 +117,8 @@ You can find the instructions on how to install the package for development in [
 
 To run the tests and linters, use
 
-```
-hatch run test
+```bash
+hatch test
 ```
 
 For information on how to contribute your developments back to the Vega-Altair repository, see

tests/test_toplevel.py

@@ -8,5 +8,5 @@ def test_completeness_of__all__():
 
     # If the assert statement fails below, there are probably either new objects
     # in the top-level Altair namespace or some were removed.
-    # In that case, run tools/update_init_file.py to update __all__
+    # In that case, run `hatch run update-init-file` to update __all__
     assert alt.__all__ == relevant_attributes