doc: Add build hooks

build/hooks/default.nix

@@ -17,7 +17,11 @@ let
 
 in
 {
-  # Build hook used to build PEP-621/setuptools projects
+  /*
+    Undo any `$PYTHONPATH` changes done by nixpkgs Python infrastructure dependency propagation.
+
+    Used internally by `pyprojectHook`.
+  */
   pyprojectConfigureHook = callPackage (
     { python }:
     makeSetupHook {
@@ -36,7 +40,11 @@ in
     } ./pyproject-configure-hook.sh
   ) { };
 
-  # Build hook used to build PEP-621/setuptools projects
+  /*
+    Build a pyproject.toml/setuptools project.
+
+    Used internally by `pyprojectHook`.
+  */
   pyprojectBuildHook = callPackage (
     _:
     makeSetupHook {
@@ -51,13 +59,23 @@ in
     } ./pyproject-build-hook.sh
   ) { };
 
+  /*
+    Symlink prebuilt wheel sources.
+
+    Used internally by `pyprojectWheelHook`.
+  */
   pyprojectWheelDistHook = callPackage (
     _:
     makeSetupHook {
       name = "pyproject-wheel-dist-hook";
     } ./pyproject-wheel-dist-hook.sh
   ) { };
 
+  /*
+    Install built projects from dist/*.whl.
+
+    Used internally by `pyprojectHook`.
+  */
   pyprojectInstallHook =
     callPackage
       (
@@ -73,6 +91,11 @@ in
         inherit (buildPackages) uv;
       };
 
+  /*
+    Install hook using pypa/installer.
+
+    Used instead of `pyprojectInstallHook` for cross compilation support.
+  */
   pyprojectPypaInstallHook = callPackage (
     { pythonPkgsBuildHost }:
     makeSetupHook {
@@ -84,6 +107,11 @@ in
     } ./pyproject-pypa-install-hook.sh
   ) { };
 
+  /*
+    Clean up any shipped bytecode in package output and recompile.
+
+    Used internally by `pyprojectHook`.
+  */
   pyprojectBytecodeHook = callPackage (
     _:
     makeSetupHook {
@@ -103,6 +131,11 @@ in
     } ./pyproject-bytecode-hook.sh
   ) { };
 
+  /*
+    Create `pyproject.nix` setup hook in package output.
+
+    Used internally by `pyprojectHook`.
+  */
   pyprojectOutputSetupHook = callPackage (
     _:
     makeSetupHook {
@@ -113,6 +146,11 @@ in
     } ./pyproject-output-setup-hook.sh
   ) { };
 
+  /*
+    Create a virtual environment from buildInputs
+
+    Used internally by `mkVirtualEnv`.
+  */
   pyprojectMakeVenvHook = callPackage (
     { python }:
     makeSetupHook {
@@ -124,7 +162,12 @@ in
     } ./pyproject-make-venv-hook.sh
   ) { };
 
-  # Meta hook aggregating the default pyproject.toml/setup.py install behaviour and adds Python
+  /*
+    Meta hook aggregating the default pyproject.toml/setup.py install behaviour and adds Python.
+
+    This is the default choice for both pyproject.toml & setuptools projects.
+  */
+  #
   pyprojectHook =
     callPackage
       (
@@ -157,6 +200,11 @@ in
         })
       );
 
+  /*
+    Hook used to build prebuilt wheels.
+
+    Use instead of pyprojectHook.
+  */
   pyprojectWheelHook = hooks.pyprojectHook.override {
     pyprojectBuildHook = hooks.pyprojectWheelDistHook;
   };

doc/src/SUMMARY.md

@@ -42,6 +42,7 @@
   - [lib](./build/lib/default.nix)
     - [renderers](./build/lib/renderers.nix)
     - [resolvers](./build/lib/resolvers.nix)
+  - [hooks](./build/hooks/default.nix)
 
 # Contributing