docs can be built now without installing kwant (useful i.a. for the debian package)

INSTALL

@@ -468,19 +468,22 @@ Python's configparser module
 Building the documentation
 ==========================
 
-To build the documentation, Kwant has to be installed as described above.
-Additionally, the `Sphinx documentation generator <http://sphinx.pocoo.org/>`_
-is required.  If PDF documentation is to be built, the tools from the `libRSVG
-<http://live.gnome.org/LibRsvg>`_ (Debian/Ubuntu package ``librsvg2-bin``) are
-needed to convert SVG drawings into the PDF format.
-
-HTML documentation is built by entering the ``doc`` subdirectory of the
-Kwant package and executing ``make html``.  PDF documentation is generated by
-executing ``make latex`` followed by a ``make all-pdf`` in ``doc/build/latex``.
+To build the documentation, the `Sphinx documentation generator
+<http://sphinx.pocoo.org/>`_ is required.  If PDF documentation is to be built,
+the tools from the `libRSVG <http://live.gnome.org/LibRsvg>`_ (Debian/Ubuntu
+package ``librsvg2-bin``) are needed to convert SVG drawings into the PDF
+format.
+
+As a prerequisite for building the documentation, Kwant must have been built
+successfully using ``./setup.py build`` as described above (or Kwant must be
+already installed in Python's search path).  HTML documentation is built by
+entering the ``doc`` subdirectory of the Kwant package and executing ``make
+html``.  PDF documentation is generated by executing ``make latex`` followed by
+``make all-pdf`` in ``doc/build/latex``.
 
 Because of some quirks of how Sphinx works, it might be necessary to execute
 ``make clean`` between building HTML and PDF documentation.  If this is not
-done, Sphinx might mistakenly use PNG files for PDF output or other problems may
+done, Sphinx may mistakenly use PNG files for PDF output or other problems may
 appear.
 
 

doc/source/conf.py

@@ -12,6 +12,10 @@
 # serve to show the default.
 
 import sys, os
+
+from distutils.util import get_platform
+sys.path.insert(0, "../../build/lib.{0}-{1}.{2}".format(
+        get_platform(), *sys.version_info[:2]))
 import kwant
 
 # -- General configuration -----------------------------------------------------

doc/source/images/_defs.py

+################################################################
+# Prepend Kwant's build directory to sys.path
+################################################################
+import sys
+from distutils.util import get_platform
+sys.path.insert(0, "../../../build/lib.{0}-{1}.{2}".format(
+        get_platform(), *sys.version_info[:2]))
+
+################################################################
+# Define constants for plotting
+################################################################
 pt_to_in = 1. / 72.
 
 # Default width of figures in pts

doc/source/images/ab_ring.py.diff

 --- original
 +++ modified
-@@ -16,6 +16,7 @@
+@@ -9,6 +9,7 @@
+ #    example, but in the tutorial main text)
+ #  - Modifcations of hoppings/sites after they have been added
  
- # For plotting
- from matplotlib import pyplot
 +import _defs
+ from cmath import exp
+ from math import pi
  
- 
- def make_system(a=1, t=1.0, W=10, r1=10, r2=20):
 @@ -37,12 +38,13 @@
      sys[lat.shape(ring, (0, r1 + 1))] = 4 * t
      sys[lat.neighbors()] = -t

doc/source/images/band_structure.py.diff

 --- original
 +++ modified
-@@ -10,6 +10,7 @@
+@@ -6,6 +6,7 @@
+ # --------------------------
+ #  - Computing the band structure of a finalized lead.
  
- # For plotting.
- from matplotlib import pyplot
 +import _defs
+ import kwant
  
- def make_lead(a=1, t=1.0, W=10):
-     # Start with an empty lead with a single square lattice
+ # For plotting.
 @@ -33,10 +34,19 @@
  
  def main():

doc/source/images/closed_system.py.diff

 --- original
 +++ modified
-@@ -17,6 +17,7 @@
+@@ -8,6 +8,7 @@
+ #  - Use of `hamiltonian_submatrix` in order to obtain a Hamiltonian
+ #    matrix.
  
- # For plotting
- from matplotlib import pyplot
 +import _defs
- 
- 
- def make_system(a=1, t=1.0, r=10):
+ from cmath import exp
+ import numpy as np
+ import kwant
 @@ -65,29 +66,39 @@
  
          energies.append(ev)

doc/source/images/graphene.py.diff

 --- original
 +++ modified
-@@ -17,6 +17,7 @@
+@@ -8,6 +8,7 @@
+ #    lattice, namely graphene
  
- # For plotting
- from matplotlib import pyplot
+ from __future__ import division  # so that 1/2 == 0.5, and not 0
 +import _defs
+ from math import pi, sqrt, tanh
  
- 
- # Define the graphene lattice
+ import kwant
 @@ -100,22 +101,40 @@
          smatrix = kwant.smatrix(sys, energy)
          data.append(smatrix.transmission(0, 1))

doc/source/images/quantum_well.py.diff

 --- original
 +++ modified
-@@ -10,6 +10,7 @@
+@@ -6,6 +6,7 @@
+ # --------------------------
+ #  - Functions as values in Builder
  
- # For plotting
- from matplotlib import pyplot
 +import _defs
+ import kwant
  
- 
- def make_system(a=1, t=1.0, W=10, L=30, L_well=10):
+ # For plotting
 @@ -52,19 +53,25 @@
          smatrix = kwant.smatrix(sys, energy, args=[-welldepth])
          data.append(smatrix.transmission(1, 0))

doc/source/images/quantum_wire.py.diff

 --- original
 +++ modified
-@@ -10,6 +10,7 @@
+@@ -8,6 +8,7 @@
+ #  - Making scattering region and leads
+ #  - Using the simple sparse solver for computing Landauer conductance
  
++import _defs
  from matplotlib import pyplot
  import kwant
-+import _defs
- 
- # First, define the tight-binding system
  
 @@ -65,7 +66,10 @@
  sys.attach_lead(right_lead)

doc/source/images/spin_orbit.py.diff

 --- original
 +++ modified
-@@ -17,6 +17,7 @@
+@@ -10,6 +10,7 @@
+ # --------------------------
+ #  - Numpy matrices as values in Builder
  
- # For matrix support
- import tinyarray
 +import _defs
+ import kwant
  
- # define Pauli-matrices for convenience
- sigma_0 = tinyarray.array([[1, 0], [0, 1]])
+ # For plotting
 @@ -67,19 +68,24 @@
          smatrix = kwant.smatrix(sys, energy)
          data.append(smatrix.transmission(1, 0))

doc/source/images/superconductor_band_structure.py.diff

 --- original
 +++ modified
-@@ -17,6 +17,7 @@
+@@ -10,6 +10,7 @@
+ #  - Main motivation is to contrast to the implementation of superconductivity
+ #    in tutorial5b.py
  
- # For plotting
- from matplotlib import pyplot
 +import _defs
+ import kwant
  
- tau_x = tinyarray.array([[0, 1], [1, 0]])
- tau_z = tinyarray.array([[1, 0], [0, -1]])
+ import numpy as np
 @@ -46,11 +47,20 @@
      # Make system and finalize it right away.
      lead = make_lead().finalized()

doc/source/images/superconductor_transport.py.diff

 --- original
 +++ modified
-@@ -11,6 +11,7 @@
+@@ -7,6 +7,7 @@
+ # - Implementing electron and hole ("orbital") degrees of freedom
+ #   using different lattices
  
- # For plotting
- from matplotlib import pyplot
 +import _defs
+ import kwant
  
- 
- def make_system(a=1, W=10, L=10, barrier=1.5, barrierpos=(3, 4),
+ # For plotting
 @@ -82,19 +83,24 @@
                      smatrix.transmission(0, 0) +
                      smatrix.transmission(1, 0))