[red-knot] document test framework (#13695)

This adds documentation for the new test framework.

I also added documentation for the planned design of features we haven't
built yet (clearly marked as such), so that this doc can become the sole
source of truth for the test framework design (we don't need to refer
back to the original internal design document.)

Also fixes a few issues in the test framework implementation that were
discovered in writing up the docs.

---------

Co-authored-by: T-256 <132141463+T-256@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Dhruv Manilawala <dhruvmanila@gmail.com>

.pre-commit-config.yaml

@@ -28,6 +28,7 @@ repos:
         additional_dependencies:
           - mdformat-mkdocs
           - mdformat-admon
+          - mdformat-footnote
         exclude: |
           (?x)^(
             docs/formatter/black\.md

crates/red_knot_python_semantic/resources/README.md

@@ -0,0 +1,4 @@
+Markdown files within the `mdtest/` subdirectory are tests of type inference and type checking;
+executed by the `tests/mdtest.rs` integration test.
+
+See `crates/red_knot_test/README.md` for documentation of this test format.

crates/red_knot_python_semantic/tests/mdtest.rs

@@ -1,6 +1,7 @@
 use red_knot_test::run;
 use std::path::PathBuf;
 
+/// See `crates/red_knot_test/README.md` for documentation on these tests.
 #[rstest::rstest]
 fn mdtest(#[files("resources/mdtest/**/*.md")] path: PathBuf) {
     let crate_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"))