From de3593489c6864665099e6337e4c482c99c2efe7 Mon Sep 17 00:00:00 2001
From: Ethan Rooke <ethan@roo.ke>
Date: Sun, 26 Feb 2023 23:03:32 -0600
Subject: [PATCH] Document ModuleNotFoundError

Poetry does not lock down information about the build system used to
build dependencies. As such poetry2nix cannot automatically figure out
build inputs. https://github.com/nix-community/poetry2nix/issues/568

This documents how to help poetry2nix out with figuring out buildinputs.
---
 docs/documentation/how-to.md | 45 ++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/documentation/how-to.md b/docs/documentation/how-to.md
index 28e19b77..12eaf981 100644
--- a/docs/documentation/how-to.md
+++ b/docs/documentation/how-to.md
@@ -149,6 +149,51 @@ kernel.python.python-with-numpy.projectDir = ./my-custom-python;
    Eventually, you will see the recognizable messages from JupyterLab in your terminal.
    Open up the Web UI in your browser and use your custom kernel.
 
+??? question "Did something go wrong?"
+
+    If nix fails to build a kernel with an error like the following.
+
+    ```shell
+    error: builder for '/nix/store/y44r14sxadnk0pccy8ciz8p1g6wpwbzq-python3.10-pathspec-0.11.0.drv' failed with exit code 2;
+           last 10 log lines:
+           >   File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
+           >   File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
+           >   File "<frozen importlib._bootstrap>", line 992, in _find_and_load_unlocked
+           >   File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
+           >   File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
+           >   File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
+           >   File "<frozen importlib._bootstrap>", line 1004, in _find_and_load_unlocked
+           > ModuleNotFoundError: No module named 'flit_core'
+    ```
+
+    There is some python package with a build dependency that poetry2nix is
+    unaware about. To fix this you need to tell jupyenv about the dependency
+    through an override. Create an `overrides.nix`.
+
+    ```nix title="overrides.nix"
+    final: prev: let
+      addNativeBuildInputs = drvName: inputs: {
+        "${drvName}" = prev.${drvName}.overridePythonAttrs (
+          old: {
+            nativeBuildInputs = (old.nativeBuildInputs or []) ++ inputs;
+          }
+        );
+      };
+    in
+      {} // addNativeBuildInputs "pathspec" [final.flit-core]
+    ```
+
+    Note we used `"pathspec"` here as that was the package which generated the
+    error and `final.flit-core` as that was the missing module.Add the override
+    to your kernel.
+
+    ```nix title="kernels.nix"
+    kernel.python.python-with-numpy.overrides = overrides.nix;
+    ```
+
+    Start the jupyter environment with `nix run`.
+
+
 ### Julia kernel
 
 The Julia kernel requires some stateful operations to work properly.