manual: clarify and expand nix-shell file

doc/manual/installing.rst

@@ -48,8 +48,8 @@ Installing multiple packages and making them visible to the ARTIQ commands requi
 ::
 
   let
-    # Contains the NixOS package collection. ARTIQ depends on some of them, and
-    # you may also want certain packages from there.
+    # pkgs contains the NixOS package collection. ARTIQ depends on some of them, and
+    # you may want some additional packages from there.
     pkgs = import <nixpkgs> {};
     artiq-full = import <artiq-full> { inherit pkgs; };
   in
@@ -57,25 +57,39 @@ Installing multiple packages and making them visible to the ARTIQ commands requi
       buildInputs = [
         (pkgs.python3.withPackages(ps: [
           # List desired Python packages here.
+
+          # You probably want these two.
           artiq-full.artiq
           artiq-full.artiq-comtools
-          # The board packages are also "Python" packages. You only need a board
-          # package if you intend to reflash that board (those packages contain
-          # only board firmware).
-          artiq-full.artiq-board-kc705-nist_clock
-          artiq-full.artiq-board-kasli-wipm
-          # from the NixOS package collection:
-          ps.paramiko  # needed for flashing boards remotely (artiq_flash -H)
-          ps.pandas
-          ps.numpy
-          ps.scipy
-          ps.numba
-          (ps.matplotlib.override { enableQt = true; })
-          ps.bokeh
+
+          # You need a board support package if and only if you intend to flash
+          # a board (those packages contain only board firmware).
+          # The lines below are only examples, you need to select appropriate
+          # packages for your boards.
+          #artiq-full.artiq-board-kc705-nist_clock
+          #artiq-full.artiq-board-kasli-wipm
+          #ps.paramiko  # needed if and only if flashing boards remotely (artiq_flash -H)
+
+          # The NixOS package collection contains many other packages that you may find
+          # interesting for your research. Here are some examples:
+          #ps.pandas
+          #ps.numpy
+          #ps.scipy
+          #ps.numba
+          #(ps.matplotlib.override { enableQt = true; })
+          #ps.bokeh
+          #ps.cirq
+          #ps.qiskit
+          #ps.qutip
         ]))
+
         # List desired non-Python packages here
-        artiq-full.openocd  # needed for flashing boards, also provides proxy bitstreams
-        pkgs.spyder
+        #artiq-full.openocd  # needed if and only if flashing boards
+        # Other potentially interesting packages from the NixOS package collection:
+        #pkgs.gtkwave
+        #pkgs.spyder
+        #pkgs.R
+        #pkgs.julia
       ];
     }