📝 Add a highlights section in README.md (#249)

* 📝 Add a highlights section in `README.md`

* 📝 "Anaconda" -> "conda-forge"

Co-authored-by: Lucas Colley <[email protected]>

* 📝 Fix typo

---------

Co-authored-by: Lucas Colley <[email protected]>

Author: jorenham

README.md

@@ -1,7 +1,7 @@
 <h1 align="center">scipy-stubs</h1>
 
 <p align="center">
-    Typing stubs for <a href="https://github.com/scipy/scipy">SciPy</a>.
+    Precise type hints for <i>all</i> of <a href="https://github.com/scipy/scipy">SciPy</a>.
 </p>
 
 <p align="center">
@@ -65,6 +65,32 @@
 
 ______________________________________________________________________
 
+## Highlights
+
+- Works out-of-the-box
+  - all that's needed is to [install `scipy-stubs`](#installation)
+  - does not require a `mypy` plugin or other configuration
+  - available on [PyPI](https://pypi.org/project/scipy-stubs/) and [conda-forge](https://anaconda.org/conda-forge/scipy-stubs)
+- Improves IDE suggestions and autocompletion
+  - ... even if you don't use static typing in your code
+  - no additional plugins required
+- 0% runtime overhead
+  - not even a single import is required
+- 100% coverage of the [public SciPy API](https://docs.scipy.org/doc/scipy-1.14.1/reference/index.html)
+  - also covers most of the private API
+- Precise type-hinting of dtypes and [shape-types](https://github.com/numpy/numpy/issues/16544)
+  - works with all "array-likes" and "dtype-likes"
+  - many of the functions that return an array are *shape-typed*
+  - shape-typing is optional: all functions still accept arrays with unknown shape-type
+- Type-checker agnostic
+  - works with at least [`mypy`](https://github.com/KotlinIsland/basedmypy),
+    [`pyright`](https://github.com/DetachHead/basedpyright)/pylance and [`ruff`](https://github.com/astral-sh/ruff)
+  - ... even in the strict mode
+  - compatible with the [Python Typing Spec](https://typing.readthedocs.io/en/latest/spec/index.html)
+- [SPEC 0](https://scientific-python.org/specs/spec-0000/) compliant
+  - Supports Python ≥ 3.10
+  - Supports NumPy ≥ 1.24
+
 ## Installation
 
 <table>
@@ -93,12 +119,40 @@ conda install conda-forge::scipy-stubs
 
 </table>
 
+## Supported static 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.
+
+## 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.
+
+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).
+
 ## `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".
+However, a small portion uses `Untyped` (an 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
@@ -126,34 +180,6 @@ from 🌑 (100% `Untyped`) to 🌕 (0% `Untyped`).
 | `stats`       |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
 | *`_lib`*      |          ✔️           |     ✔️     |     ✔️      |       ✔️       |  🌕   |
 
-## Supported static 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.
-
-## 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.
-
-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