Merge pull request #206 from jorenham/improved-readme

Improved `README.md`

README.md

@@ -72,11 +72,19 @@ ______________________________________________________________________
 pip install scipy-stubs
 ```
 
-## Development Status
+## `scipy` coverage
+
+The entire public API of `scipy` is **fully annotated** and **verifiably valid**.
+For the most part, this can also be said about `scipy`'s private API and other internal machinery.
+
+However, a small portion uses `Untyped` (and alias of `Any`) as "placeholder annotations".
+In those cases static type-checkers won't do any type-checking, and won't bother you with errors or warnings.
+
+The following table shows the (subjective) proportion of `scipy-stubs` that is(n't) annotated with `Untyped`, ranging
+from 🌑 (100% `Untyped`) to 🌕 (0% `Untyped`).
 
 | `scipy._`     | `ruff` & `flake8-pyi` | `stubtest` | `basedmypy` | `basedpyright` | phase |
 | :------------ | :-------------------: | :--------: | :---------: | :------------: | :---: |
-| `_lib`        |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
 | `cluster`     |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
 | `constants`   |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌝   |
 | `datasets`    |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌝   |
@@ -95,23 +103,43 @@ pip install scipy-stubs
 | `spatial`     |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
 | `special`     |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌔   |
 | `stats`       |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
+| *`_lib`*      |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
 
-## Version Compatibility
+## Supported static type-checkers
 
-### Type-checkers
+1. [`basedpyright`](https://github.com/DetachHead/basedpyright) (recommended)
+1. [`basedmypy`](https://github.com/KotlinIsland/basedmypy)
+1. [`pyright`](https://pyright.readthedocs.io/en/latest/index.html)
+1. [`mypy`](https://mypy.readthedocs.io/en/stable/index.html) (not recommended, see [erictraut/mypy_issues](https://github.com/erictraut/mypy_issues))
 
 For validation and testing, `scipy-stubs` primarily uses [`basedmypy`](https://github.com/KotlinIsland/basedmypy) (a `mypy` fork)
 and [`basedpyright`](https://github.com/DetachHead/basedpyright) (a `pyright` fork).
 They are in generally stricter than `mypy` and `pyright`, so you can assume compatibility with `mypy` and `pyright` as well.
 But if you find that this isn't the case, then don't hesitate to open an issue or submit a pull request.
 
-### Required dependencies
+## Versioning and requirements
 
 The versioning scheme of `scipy-stubs` includes the compatible `scipy` version as `{scipy_version}.{stubs_version}`.
 Even though `scipy-stubs` doesn't enforce an upper bound on the `scipy` version, later `scipy` versions aren't guaranteed to be
 fully compatible.
 
-Apart from `scipy`'s own dependencies, (e.g. `numpy`), the only other required dependency is
-[`optype`](https://github.com/jorenham/optype), which itself only depends on `typing_extensions`.
+The supported range of `numpy` versions are specified in [`SPEC 0`](https://scientific-python.org/specs/spec-0000/), which
+`scipy-stubs` aims to follow as close as feasible.
+
+Currently, `scipy-stubs` has one required dependency: [`optype`](https://github.com/jorenham/optype).
+This is essential for `scipy-stubs` to work properly, as it relies heavily on it for annotating (shaped) array-likes,
+scalar-likes, shape-typing in general, and much more.
+At the moment, `scipy-stubs` requires the latest version `optype`.
 
 The exact version requirements are specified in the [`pyproject.toml`](pyproject.toml).
+
+## See also
+
+- [scipy/scipy#21614](https://github.com/scipy/scipy/issues/21614): On why `scipy-stubs` is a separate package, and not part of
+  `scipy` (yet).
+- [microsoft/python-type-stubs#321](https://github.com/microsoft/python-type-stubs/pull/321): The removal of Microsoft's
+  `scipy-stubs` — that used to be bundled with Pylance — in favor of `scipy-stubs`.
+- [`optype`](https://github.com/jorenham/optype): The fundamental typing package that made `scipy-stubs` possible.
+- [`basedpyright`](https://github.com/detachhead/basedpyright): The recommended type-checker to use with `scipy-stubs`.
+- [`basedmypy`](https://github.com/KotlinIsland/basedmypy): A [less-broken](https://github.com/erictraut/mypy_issues) `mypy` fork,
+  with a bunch of cool extra features.