From 42e3727aa2bfbac5a13396fef388324fbb3f080c Mon Sep 17 00:00:00 2001
From: Erik Arvstedt <erik.arvstedt@gmail.com>
Date: Wed, 25 Jul 2018 21:29:25 +0200
Subject: [PATCH] python docs: improve override example

1. Use the same approach like in the overlay example:
   Override `python` instead of `pythonPackages` so that
   `python.pkgs` refers to the new package set like `pythonPackages`.

   This also fixes a bug in the original example where
   `pkgs.fetchgit` was not in scope.

   Add an extra example to illustrate how to override just a
   package set.

2. Fix mix-up between `super` and `self` in the explanation text.
   Also, simplify the explanation.
---
 doc/languages-frameworks/python.section.md | 30 +++++++++++++++-------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index dcb0ea0600b..b42d2e67bcf 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -1006,14 +1006,14 @@ folder and not downloaded again.
 If you need to change a package's attribute(s) from `configuration.nix` you could do:
 
 ```nix
-  nixpkgs.config.packageOverrides = superP: {
-    pythonPackages = superP.pythonPackages.override {
-      overrides = self: super: {
-        bepasty-server = super.bepasty-server.overrideAttrs ( oldAttrs: {
-          src = pkgs.fetchgit {
+  nixpkgs.config.packageOverrides = super: {
+    python = super.python.override {
+      packageOverrides = python-self: python-super: {
+        bepasty-server = python-super.bepasty-server.overrideAttrs (oldAttrs: {
+          src = super.fetchgit {
             url = "https://github.com/bepasty/bepasty-server";
-            sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
             rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
+            sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
           };
         });
       };
@@ -1021,11 +1021,23 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul
   };
 ```
 
-If you are using the `bepasty-server` package somewhere, for example in `systemPackages` or indirectly from `services.bepasty`, then a `nixos-rebuild switch` will rebuild the system but with the `bepasty-server` package using a different `src` attribute. This way one can modify `python` based software/libraries easily. Using `self` and `super` one can also alter dependencies (`buildInputs`) between the old state (`self`) and new state (`super`).
+If you are using the `bepasty-server` package somewhere, for example in `systemPackages` or indirectly from `services.bepasty`, then a `nixos-rebuild switch` will rebuild the system but with the `bepasty-server` package using a different `src` attribute. This way one can modify `python` based software/libraries easily.
+Note that `python-super` refers to the old package set and `python-self`
+to the new, overridden version.
+
+To modify only a Python package set instead of a whole Python derivation, use this snippet:
+
+```nix
+  myPythonPackages = pythonPackages.override {
+    overrides = self: super: {
+      bepasty-server = ...;
+    };
+  }
+```
 
 ### How to override a Python package using overlays?
 
-To alter a python package using overlays, you would use the following approach:
+Use the following overlay template:
 
 ```nix
 self: super:
@@ -1035,8 +1047,8 @@ self: super:
       bepasty-server = python-super.bepasty-server.overrideAttrs (oldAttrs: {
         src = self.pkgs.fetchgit {
           url = "https://github.com/bepasty/bepasty-server";
-          sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
           rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
+          sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
         };
       });
     };