From 4dfd2a313f4dc1b108befdaa5721bb8a1185b17b Mon Sep 17 00:00:00 2001
From: adisbladis <adisbladis@gmail.com>
Date: Wed, 25 Sep 2024 07:55:17 +0000
Subject: [PATCH] doc: Add build hooks

---
 build/hooks/default.nix | 54 ++++++++++++++++++++++++++++++++++++++---
 doc/src/SUMMARY.md      |  1 +
 2 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/build/hooks/default.nix b/build/hooks/default.nix
index b6e6949..c4e0f75 100644
--- a/build/hooks/default.nix
+++ b/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,6 +59,11 @@ in
     } ./pyproject-build-hook.sh
   ) { };
 
+  /*
+    Symlink prebuilt wheel sources.
+
+    Used internally by `pyprojectWheelHook`.
+  */
   pyprojectWheelDistHook = callPackage (
     _:
     makeSetupHook {
@@ -58,6 +71,11 @@ in
     } ./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;
   };
diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
index 7c3a68a..fa64d5e 100644
--- a/doc/src/SUMMARY.md
+++ b/doc/src/SUMMARY.md
@@ -41,6 +41,7 @@
   - [lib](./build/lib/default.nix)
     - [renderers](./build/lib/renderers.nix)
     - [resolvers](./build/lib/resolvers.nix)
+  - [hooks](./build/hooks/default.nix)
 
 # Contributing