Docs: simplify repdroducible guide

- Rephrase the `readthedocs.yaml` section since it's _mandatory_ now
- Add a small YAML that shows pinning OS and tools
- Only show `python.install.requirements` for Python dependencies section
- Remove "Good" small section since we removed the "Bad" one already
- Remove "Check list" since it's just duplicated content

docs/user/guides/reproducible-builds.rst

@@ -12,37 +12,42 @@ so that you can focus on content.
    :local:
    :depth: 3
 
-Use a ``.readthedocs.yaml`` configuration file
+Define OS and tool versions in the config file
 ----------------------------------------------
 
-We recommend using a :doc:`configuration file </config-file/v2>` to manage your documentation.
-Our config file *provides you per version settings*,
+We recommend defining the explicit version of the OS and tool versions used to build your documentation
+using the ``.readthedocs.yaml``.
+This file file *provides you per version settings*,
 and *those settings live in your Git repository*.
 
 This allows you to validate changes using :doc:`pull requests </pull-requests>`,
 and ensures that all your versions can be rebuilt from a reproducible configuration.
 
-Use a requirements file for Python dependencies
------------------------------------------------
-
-We recommend using a Pip :ref:`requirements file <pip:requirements-file-format>` or Conda :ref:`environment file <config-file/v2:conda.environment>` to :term:`pin <pinning>` Python dependencies.
-This ensures that top-level dependencies and extensions don't change.
-
-A configuration file with explicit dependencies looks like this:
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
+   :emphasize-lines: 5,7-8
 
    version: 2
 
+   # Explicitly set the OS and Python versions
    build:
-     os: "ubuntu-22.04"
+     os: "ubuntu-24.04"
      tools:
+       nodejs: "20"
        python: "3.12"
 
-   # Build from the docs/ directory with Sphinx
-   sphinx:
-     configuration: docs/conf.py
+Use a requirements file for Python dependencies
+-----------------------------------------------
+
+We recommend using a Pip :ref:`requirements file <pip:requirements-file-format>` or Conda :ref:`environment file <config-file/v2:conda.environment>` to :term:`pin <pinning>` Python dependencies.
+This ensures that top-level dependencies and extensions don't change.
+
+A configuration file with explicit dependencies looks like this:
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+   :emphasize-lines: 4
 
    # Explicitly set the version of Python and its requirements
    python:
@@ -72,14 +77,10 @@ and they can upgrade without warning if you do not pin these packages as well.
 
 We recommend `pip-tools`_ to help address this problem.
 It allows you to specify a ``requirements.in`` file with your top-level dependencies,
-and it generates a ``requirements.txt`` file with the full set of transitive dependencies.
+and it generates a ``requirements.txt`` file with the full set of transitive dependencies pinned.
 
 .. _pip-tools: https://pip-tools.readthedocs.io/en/latest/
 
-✅ Good:
-    All your transitive dependencies are defined,
-    which ensures new package releases will not break your docs.
-
    .. code-block::
       :caption: docs/requirements.in
 
@@ -139,21 +140,6 @@ and it generates a ``requirements.txt`` file with the full set of transitive dep
       urllib3==1.26.13
           # via requests
 
-Check list ✅
--------------
-
-If you followed this guide,
-you have :term:`pinned <pinning>`:
-
-* tool versions (Python, Node)
-* top-level dependencies (Sphinx, Sphinx extensions)
-* transitive dependencies (Pytz, Jinja2)
-
-This will protect your builds from failures because of a random tool or dependency update.
-
-You do still need to upgrade your dependencies from time to time,
-but you should do that on your own schedule.
-
 .. seealso::
 
    :doc:`/config-file/v2`