📝 docs: rewrite for clarity and accessibility

The documentation assumed familiarity with Python packaging internals.
Rewrote all pages with plain language, added concept definitions before
using them, and reorganized content to follow a logical learning path.

Author: gaborbernat

docs/explanation.rst

@@ -1,16 +1,17 @@
-How py-discovery works
-======================
+How it works
+============
 
-Discovery strategy
-------------------
+Where does py-discovery look?
+-------------------------------
 
-The :class:`~py_discovery.Builtin` class searches for Python interpreters in the following order.
+When you call :class:`~py_discovery.Builtin` ``.run()``, the library checks several locations in
+order. It stops as soon as it finds an interpreter that matches your spec.
 
 .. mermaid::
 
     flowchart TD
         Start["Builtin.run()"] --> AbsPath{"Is spec an<br>absolute path?"}
-        AbsPath -->|Yes| TryAbs["Try path directly"]
+        AbsPath -->|Yes| TryAbs["Use path directly"]
         AbsPath -->|No| TryFirst["try_first_with paths"]
         TryFirst --> RelPath{"Is spec a<br>relative path?"}
         RelPath -->|Yes| TryRel["Resolve relative to cwd"]
@@ -27,22 +28,24 @@ The :class:`~py_discovery.Builtin` class searches for Python interpreters in the
         UV --> Verify
 
         Verify{{"Verify candidate<br>(subprocess call)"}}
-        Verify -->|Satisfies spec| Cache["Cache and return"]
+        Verify -->|Matches spec| Cache["Cache and return"]
         Verify -->|No match| Next["Try next candidate"]
 
         style Start fill:#4a90d9,stroke:#2a5f8f,color:#fff
         style Verify fill:#d9904a,stroke:#8f5f2a,color:#fff
         style Cache fill:#4a9f4a,stroke:#2a6f2a,color:#fff
         style Next fill:#d94a4a,stroke:#8f2a2a,color:#fff
 
-Each candidate is verified by running it as a subprocess to collect its metadata (version, architecture, platform,
-sysconfig paths, and more). Verified interpreters are cached to avoid repeating this subprocess call.
+Each candidate is verified by running it as a subprocess and collecting its metadata (version,
+architecture, platform, sysconfig values, etc.). This subprocess call is the expensive part, which
+is why results are cached.
 
-Shim resolution
----------------
+How version-manager shims are handled
+-----------------------------------------
 
-When a spec like ``python3.12`` resolves to a version-manager shim (e.g., ``~/.pyenv/shims/python3.12``),
-py-discovery detects this and resolves it to the real binary.
+Version managers like `pyenv <https://github.com/pyenv/pyenv>`_ install thin wrapper scripts called
+**shims** (e.g., ``~/.pyenv/shims/python3.12``) that redirect to the real interpreter. py-discovery
+detects these shims and resolves them to the actual binary.
 
 .. mermaid::
 
@@ -59,17 +62,14 @@ py-discovery detects this and resolves it to the real binary.
         style Use fill:#4a9f4a,stroke:#2a6f2a,color:#fff
         style Skip fill:#d94a4a,stroke:#8f2a2a,color:#fff
 
-For `mise <https://mise.jdx.dev/>`_ and `asdf <https://asdf-vm.com/>`_, the ``MISE_DATA_DIR`` and ``ASDF_DATA_DIR``
-directories are searched. The shim directory is identified via the ``PYENV_ROOT``, ``MISE_DATA_DIR``, or
-``ASDF_DATA_DIR`` environment variables.
+`mise <https://mise.jdx.dev/>`_ and `asdf <https://asdf-vm.com/>`_ work similarly, using the
+``MISE_DATA_DIR`` and ``ASDF_DATA_DIR`` environment variables to locate their installations.
 
-Cache design
-------------
+How caching works
+-------------------
 
-The :class:`~py_discovery.DiskCache` stores interpreter metadata as JSON files under
-``<root>/py_info/4/<sha256>.json``, where the hash is derived from the interpreter path. File locking via
-`filelock <https://py-filelock.readthedocs.io/>`_
-ensures safe concurrent access.
+Querying an interpreter requires a subprocess call, which is slow. The cache avoids repeating this
+work by storing the result as a JSON file keyed by the interpreter's path.
 
 .. mermaid::
 
@@ -85,16 +85,15 @@ ensures safe concurrent access.
         style Return fill:#4a9f4a,stroke:#2a6f2a,color:#fff
         style Run fill:#d9904a,stroke:#8f5f2a,color:#fff
 
-The cache layer uses a :class:`typing.Protocol` (:class:`~py_discovery.PyInfoCache`), so any object with the right
-method signatures works as a cache backend -- no inheritance required. Two built-in implementations are provided:
+The built-in :class:`~py_discovery.DiskCache` stores files under ``<root>/py_info/4/<sha256>.json``
+with `filelock <https://py-filelock.readthedocs.io/>`_-based locking for safe concurrent access. You
+can also pass ``cache=None`` to disable caching, or implement your own backend (see
+:doc:`/how-to/standalone-usage`).
 
-- :class:`~py_discovery.DiskCache` -- persistent JSON + `filelock <https://py-filelock.readthedocs.io/>`_ storage.
-- ``cache=None`` -- disables caching, useful for one-shot scripts or testing.
+Spec format reference
+-----------------------
 
-Spec format
------------
-
-A spec string follows the pattern ``[impl][version][t][-arch][-machine]``.
+A spec string follows the pattern ``[impl][version][t][-arch][-machine]``. Every part is optional.
 
 .. mermaid::
 
@@ -111,36 +110,44 @@ A spec string follows the pattern ``[impl][version][t][-arch][-machine]``.
         style Arch fill:#d94a4a,stroke:#8f2a2a,color:#fff
         style Machine fill:#904ad9,stroke:#5f2a8f,color:#fff
 
+**Parts explained:**
+
+- **impl** -- the Python implementation name. ``python`` and ``py`` both mean "any implementation"
+  (usually CPython). Use ``cpython``, ``pypy``, or ``graalpy`` to be explicit.
+- **version** -- dotted version number (``3``, ``3.12``, or ``3.12.1``). You can also write
+  ``312`` as shorthand for ``3.12``.
+- **t** -- appended directly after the version. Matches free-threaded (no-GIL) builds only.
+- **-arch** -- ``-32`` or ``-64`` for 32-bit or 64-bit interpreters.
+- **-machine** -- the CPU instruction set: ``-arm64``, ``-x86_64``, ``-aarch64``, ``-riscv64``, etc.
+
+**Full examples:**
+
 .. list-table::
    :header-rows: 1
    :widths: 30 70
 
    * - Spec
      - Meaning
+   * - ``3.12``
+     - Any Python 3.12
    * - ``python3.12``
-     - CPython 3.12 (any architecture)
+     - CPython 3.12
    * - ``cpython3.12``
      - Explicitly CPython 3.12
    * - ``pypy3.9``
      - PyPy 3.9
-   * - ``3.12``
-     - Any implementation, version 3.12
-   * - ``python3.12t``
-     - Free-threaded (no-GIL) CPython 3.12
+   * - ``python3.13t``
+     - Free-threaded (no-GIL) CPython 3.13
    * - ``python3.12-64``
      - 64-bit CPython 3.12
    * - ``python3.12-64-arm64``
      - 64-bit CPython 3.12 on ARM64
    * - ``/usr/bin/python3``
-     - Absolute path, used directly
+     - Absolute path, used directly (no search)
    * - ``>=3.11,<3.13``
-     - :pep:`440` version specifier
+     - :pep:`440` version specifier (any Python in range)
    * - ``cpython>=3.11``
-     - :pep:`440` specifier with implementation filter
-
-The ``impl`` prefix is optional; ``python`` and ``py`` are treated as "any implementation." The ``t`` suffix matches
-free-threaded (no-GIL) builds. Architecture (``-32`` or ``-64``) and ISA (``-arm64``, ``-x86_64``, and others) are
-optional suffixes separated by dashes.
+     - :pep:`440` specifier restricted to CPython
 
-:pep:`440` specifiers (``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported for flexible version matching.
-Multiple specifiers can be comma-separated, for example ``>=3.11,<3.13``.
+:pep:`440` specifiers (``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported. Multiple
+specifiers can be comma-separated, for example ``>=3.11,<3.13``.

docs/how-to/standalone-usage.rst

@@ -1,80 +1,12 @@
-Advanced usage
-==============
+How-to guides
+=============
 
-Custom cache backends
----------------------
-
-Implement the :class:`~py_discovery.PyInfoCache` protocol to provide your own storage.
-
-.. mermaid::
-
-    classDiagram
-        class PyInfoCache {
-            <<Protocol>>
-            +py_info(path) ContentStore
-            +py_info_clear() None
-        }
-        class ContentStore {
-            <<Protocol>>
-            +exists() bool
-            +read() dict | None
-            +write(content) None
-            +remove() None
-            +locked() context
-        }
-        class DiskCache {
-            +root: Path
-        }
-        PyInfoCache <|.. DiskCache
-        PyInfoCache --> ContentStore
-
-.. code-block:: python
-
-   from pathlib import Path
-
-   from py_discovery import ContentStore, PyInfoCache
-
-
-   class MyContentStore:
-       def __init__(self, path: Path) -> None:
-           self._path = path
-
-       def exists(self) -> bool: ...
-
-       def read(self) -> dict | None: ...
-
-       def write(self, content: dict) -> None: ...
-
-       def remove(self) -> None: ...
-
-       def locked(self): ...
-
-
-   class MyCache:
-       def py_info(self, path: Path) -> MyContentStore: ...
-
-       def py_info_clear(self) -> None: ...
-
-The built-in :class:`~py_discovery.DiskCache` stores JSON files under ``<root>/py_info/4/<sha256>.json`` with
-`filelock <https://py-filelock.readthedocs.io/>`_-based locking. Pass ``cache=None`` to disable caching entirely.
-
-Using ``get_interpreter`` directly
+Search specific directories first
 -----------------------------------
 
-For lower-level control, use :func:`~py_discovery.get_interpreter` instead of the :class:`~py_discovery.Builtin` class.
-
-.. mermaid::
-
-    flowchart TD
-        Call["get_interpreter(spec, try_first_with)"] --> First["Check try_first_with paths"]
-        First --> Normal["Normal discovery"]
-        Normal --> Result{"Found?"}
-        Result -->|Yes| Info["PythonInfo"]
-        Result -->|No| Nil["None"]
-
-        style Call fill:#4a90d9,stroke:#2a5f8f,color:#fff
-        style Info fill:#4a9f4a,stroke:#2a6f2a,color:#fff
-        style Nil fill:#d94a4a,stroke:#8f2a2a,color:#fff
+If you know a likely location for the interpreter, pass it via ``try_first_with`` to check there
+before the normal search. This is useful when you have a custom Python install outside the
+standard locations.
 
 .. code-block:: python
 
@@ -84,12 +16,11 @@ For lower-level control, use :func:`~py_discovery.get_interpreter` instead of th
    if info is not None:
        print(info.executable)
 
-The ``try_first_with`` parameter takes paths to check before the normal discovery strategy runs.
-
-Controlling the environment
----------------------------
+Restrict the search environment
+---------------------------------
 
-Pass a custom environment mapping to isolate discovery from the system environment.
+By default, py-discovery reads environment variables like ``PATH`` and ``PYENV_ROOT`` from your
+shell. You can override these to control exactly where the library looks.
 
 .. mermaid::
 
@@ -111,13 +42,10 @@ Pass a custom environment mapping to isolate discovery from the system environme
    env = {**os.environ, "PATH": "/usr/local/bin:/usr/bin"}
    discover = Builtin(python_spec=["python3.12"], env=env)
 
-This controls which ``PATH``, ``PYENV_ROOT``, ``UV_PYTHON_INSTALL_DIR``, and other environment variables are used
-during discovery.
-
-Inspecting interpreter metadata
---------------------------------
+Read interpreter metadata
+---------------------------
 
-A :class:`~py_discovery.PythonInfo` object exposes detailed interpreter metadata.
+Once you have a :class:`~py_discovery.PythonInfo`, you can inspect everything about the interpreter.
 
 .. mermaid::
 
@@ -137,17 +65,79 @@ A :class:`~py_discovery.PythonInfo` object exposes detailed interpreter metadata
 
 .. code-block:: python
 
-   from py_discovery import Builtin, DiskCache
    from pathlib import Path
 
+   from py_discovery import Builtin, DiskCache
+
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
    info = Builtin(python_spec=["python3.12"], cache=cache).run()
 
    info.executable           # Resolved path to the binary.
-   info.system_executable    # The system (non-venv) executable.
-   info.implementation       # "CPython", "PyPy", etc.
+   info.system_executable    # The underlying system interpreter (outside any venv).
+   info.implementation       # "CPython", "PyPy", "GraalPy", etc.
    info.version_info         # VersionInfo(major, minor, micro, releaselevel, serial).
    info.architecture         # 64 or 32.
    info.platform             # sys.platform value ("linux", "darwin", "win32").
-   info.sysconfig_vars       # Dict of sysconfig variables.
-   info.sysconfig_paths      # Dict of sysconfig paths.
+   info.machine              # ISA: "arm64", "x86_64", etc.
+   info.free_threaded        # True if this is a no-GIL build.
+   info.sysconfig_vars       # All sysconfig.get_config_vars() values.
+   info.sysconfig_paths      # All sysconfig.get_paths() values.
+
+Implement a custom cache backend
+-----------------------------------
+
+The built-in :class:`~py_discovery.DiskCache` stores results as JSON files with
+`filelock <https://py-filelock.readthedocs.io/>`_-based locking. If you need a different storage
+strategy (e.g., in-memory, database-backed), implement the :class:`~py_discovery.PyInfoCache`
+protocol.
+
+.. mermaid::
+
+    classDiagram
+        class PyInfoCache {
+            <<Protocol>>
+            +py_info(path) ContentStore
+            +py_info_clear() None
+        }
+        class ContentStore {
+            <<Protocol>>
+            +exists() bool
+            +read() dict | None
+            +write(content) None
+            +remove() None
+            +locked() context
+        }
+        class DiskCache {
+            +root: Path
+        }
+        PyInfoCache <|.. DiskCache
+        PyInfoCache --> ContentStore
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from py_discovery import ContentStore, PyInfoCache
+
+
+   class MyContentStore:
+       def __init__(self, path: Path) -> None:
+           self._path = path
+
+       def exists(self) -> bool: ...
+
+       def read(self) -> dict | None: ...
+
+       def write(self, content: dict) -> None: ...
+
+       def remove(self) -> None: ...
+
+       def locked(self): ...
+
+
+   class MyCache:
+       def py_info(self, path: Path) -> MyContentStore: ...
+
+       def py_info_clear(self) -> None: ...
+
+Any object that matches the protocol works -- no inheritance required.

docs/index.rst

@@ -1,10 +1,26 @@
 py-discovery
 ============
 
-A Python interpreter discovery library. ``py-discovery`` finds Python interpreters on your system by searching PATH,
-version managers (`pyenv <https://github.com/pyenv/pyenv>`_, `mise <https://mise.jdx.dev/>`_,
-`asdf <https://asdf-vm.com/>`_), the Windows registry (:pep:`514`), and `uv <https://docs.astral.sh/uv/>`_-managed
-installations. Results are cached to disk for fast repeated lookups.
+You may have multiple Python versions installed on your machine -- system Python, versions from
+`pyenv <https://github.com/pyenv/pyenv>`_, `mise <https://mise.jdx.dev/>`_,
+`asdf <https://asdf-vm.com/>`_, `uv <https://docs.astral.sh/uv/>`_, or the Windows registry
+(:pep:`514`). ``py-discovery`` finds the right one for you.
+
+Give it a requirement like ``python3.12`` or ``>=3.11,<3.13``, and it searches all known locations,
+verifies each candidate, and returns detailed metadata about the match. Results are cached to disk so
+repeated lookups are fast.
+
+.. code-block:: python
+
+   from py_discovery import Builtin, DiskCache
+   from pathlib import Path
+
+   cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
+   result = Builtin(python_spec=["python3.12"], cache=cache).run()
+   if result is not None:
+       print(result.executable)       # /usr/bin/python3.12
+       print(result.implementation)   # CPython
+       print(result.version_info[:3]) # (3, 12, 1)
 
 .. toctree::
    :caption: Tutorials