📝 docs: fix punctuation and grammar

Ensure all sentences end with proper punctuation. Fix "discover"
typo to "class" in explanation page. Standardize list item and
comment punctuation across all doc pages.

Author: gaborbernat

docs/explanation.rst

@@ -4,7 +4,7 @@ How py-discovery works
 Discovery strategy
 ------------------
 
-The :class:`~py_discovery.Builtin` discover searches for Python interpreters in the following order:
+The :class:`~py_discovery.Builtin` class searches for Python interpreters in the following order.
 
 .. mermaid::
 
@@ -31,7 +31,7 @@ The :class:`~py_discovery.Builtin` discover searches for Python interpreters in
         Verify -->|No match| Next["Try next candidate"]
 
 Each candidate is verified by running it as a subprocess to collect its metadata (version, architecture, platform,
-sysconfig paths, etc.). Verified interpreters are cached to avoid repeating this subprocess call.
+sysconfig paths, and more). Verified interpreters are cached to avoid repeating this subprocess call.
 
 Shim resolution
 ---------------
@@ -50,8 +50,8 @@ py-discovery detects this and resolves it to the real binary:
         Global -->|Yes| Use
         Global -->|No| Skip["Skip shim"]
 
-For mise and asdf, the ``MISE_DATA_DIR`` / ``ASDF_DATA_DIR`` directories are searched. The shim directory is
-identified via ``PYENV_ROOT``, ``MISE_DATA_DIR``, or ``ASDF_DATA_DIR`` environment variables.
+For mise and asdf, 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.
 
 Cache design
 ------------
@@ -73,8 +73,8 @@ ensures safe concurrent access.
 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:
 
-- :class:`~py_discovery.DiskCache` -- persistent JSON + filelock storage
-- :class:`~py_discovery.NoOpCache` -- no-op, useful for one-shot scripts or testing
+- :class:`~py_discovery.DiskCache` -- persistent JSON + filelock storage.
+- :class:`~py_discovery.NoOpCache` -- no-op, useful for one-shot scripts or testing.
 
 Spec format
 -----------
@@ -120,9 +120,9 @@ A spec string follows the pattern ``[impl][version][t][-arch][-machine]``:
 | ``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``, etc.) are optional
-suffixes separated by dashes.
+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 specifiers (``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported for flexible version matching.
-Multiple specifiers can be comma-separated: ``>=3.11,<3.13``.
+Multiple specifiers can be comma-separated, for example ``>=3.11,<3.13``.

docs/how-to/standalone-usage.rst

@@ -50,7 +50,7 @@ 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.
+The ``try_first_with`` parameter takes paths to check before the normal discovery strategy runs.
 
 Controlling the environment
 ---------------------------
@@ -82,14 +82,14 @@ A :class:`~py_discovery.PythonInfo` object exposes detailed interpreter metadata
    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.executable           # Resolved path to the binary.
+   info.system_executable    # The system (non-venv) executable.
    info.implementation       # "CPython", "PyPy", 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.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.
 
 Parsing specs without discovery
 -------------------------------

docs/index.rst

@@ -16,7 +16,7 @@ Tutorial
 :doc:`tutorial/getting-started`
    Install py-discovery, find interpreters, and inspect their metadata.
 
-How-to guides
+How-to Guides
 -------------
 
 .. toctree::

docs/tutorial/getting-started.rst

@@ -41,28 +41,28 @@ Use :class:`~py_discovery.Builtin` to find an interpreter matching a specificati
    if result is not None:
        print(result.executable)
 
-The ``python_spec`` parameter accepts a list of spec strings to try in order. The first match wins.
+The ``python_spec`` parameter accepts a list of spec strings to try in order, and the first match wins.
 
 Spec syntax
 -----------
 
 Specs follow the pattern ``[impl][version][t][-arch][-machine]``:
 
-- ``python3.12`` -- 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 CPython 3.12
-- ``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
-- ``>=3.11,<3.13`` -- PEP 440 version specifier
-- ``cpython>=3.11`` -- PEP 440 specifier with implementation filter
+- ``python3.12`` -- 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 CPython 3.12.
+- ``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.
+- ``>=3.11,<3.13`` -- PEP 440 version specifier.
+- ``cpython>=3.11`` -- PEP 440 specifier with implementation filter.
 
 Without caching
 ---------------
 
-Pass ``cache=None`` to skip caching entirely. Each discovery will invoke the interpreter subprocess:
+Pass ``cache=None`` to skip caching entirely; each discovery will invoke the interpreter subprocess directly.
 
 .. code-block:: python