Update nanobind-bazel docs with latest developments (#842)

* Update nanobind-bazel docs with latest developments

`nanobind_bazel` v2.4.0 was released on the BCR. The MODULE.bazel code example
was thus updated, as is tradition, along with two more user-facing changes:

1. The minimum Bazel version was increased to Bazel 7, since we need to use a
sufficiently new `rules_python` for free-threading support.
2. The `@nanobind_bazel//:free_threading` flag was removed, since it was not
that useful - you still needed to give `rules_python`'s free-threading flag
separately to request a free-threaded toolchain, and supplying it did not
even guarantee a free-threading build. Now, we just use `rules_python`'s
free-threading flag value directly instead.

* Add section on free-threaded extension builds with nanobind_bazel

Presents the necessary toolchain setup in a code block, and mentions the
flag name that must be set for a free-threaded libnanobind build.

docs/api_bazel.rst

@@ -155,15 +155,3 @@ following flag settings.
     version. Allowed values are ``"cp312"``, ``"cp313"``, which target the
     stable ABI starting from Python 3.12 or 3.13, respectively. By default, all
     extensions are built without any ABI limitations.
-
-.. py:function:: @nanobind_bazel//:free_threading (boolean)
-
-    Build nanobind extensions with a Python toolchain in free-threaded mode.
-    If given, the currently configured Python toolchain must support free-threading,
-    otherwise, the build will result in a compilation error.
-    Only relevant for CPython 3.13+, since support for free-threaded Python was
-    introduced in CPython 3.13.
-    For more information on free-threaded extension support in nanobind, refer to the
-    relevant :ref:`documentation section <free-threaded>`.
-
-    *New in nanobind-bazel version 2.2.0.*

docs/bazel.rst

@@ -27,8 +27,8 @@ in your MODULE.bazel file:
     # Place this in your MODULE.bazel file.
     # The major version of nanobind-bazel is equal to the version
     # of the internally used nanobind.
-    # In this case, we are building bindings with nanobind v2.2.0.
-    bazel_dep(name = "nanobind_bazel", version = "2.2.0")
+    # In this case, we are building bindings with nanobind v2.4.0.
+    bazel_dep(name = "nanobind_bazel", version = "2.4.0")
 
 To instead use a development version from GitHub, you can declare the
 dependency as a ``git_override()`` in your MODULE.bazel:
@@ -57,7 +57,7 @@ and then declare it as a ``local_path_override()`` dependency:
 
 .. note::
 
-    At minimum, Bazel version 6.4.0 is required to use nanobind-bazel.
+    At minimum, Bazel version 7.0.0 is required to use nanobind-bazel.
 
 
 .. _bazel-build:
@@ -139,6 +139,30 @@ Naturally, since stub generation relies on the given shared object files, the
 actual extensions are built in the process before invocation of the stub
 generation script.
 
+Building extensions for free-threaded Python
+--------------------------------------------
+
+Starting from CPython 3.13, bindings extensions can be built for a free-threaded
+CPython interpreter. This requires two things: First, an eligible toolchain must
+be defined in your MODULE.bazel file, e.g. like so:
+
+.. code-block:: python
+
+    bazel_dep(name = "rules_python", version = "1.0.0")
+
+    python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+    python.toolchain(python_version = "3.13")
+
+And secondly, the ``@rules_python//python/config_settings:py_freethreaded`` flag must
+be set to "yes" when building your nanobind extension target, e.g. as
+``bazel build //path/to:my_ext --@rules_python//python/config_settings:py_freethreaded=yes``.
+
+Then, ``rules_python`` will bootstrap a free-threaded version of your target interpreter,
+and ``nanobind_bazel`` will define the ``NB_FREE_THREADED`` macro for the libnanobind
+build, indicating that nanobind should be built with free-threading support.
+For a comprehensive overview on nanobind with free-threaded Python, refer to the
+:ref:`free-threading documentation <free-threaded>`.
+
 nanobind-bazel and Python packaging
 -----------------------------------