add explicit documentation on lead numbering

It was not previously made explicit anywhere in the docs on how
the leads were numbered. This commit adds a line to the docstring
of `kwant.builder.Builder.attach_lead` which explains the meaning
of the return value. It also adds a few lines to the first tutorial
explaining the numbering.

doc/source/tutorial/tutorial1.rst

@@ -165,8 +165,9 @@ isolated, infinite is attached at the correct position using
     :start-after: #HIDDEN_BEGIN_fskr
     :end-before: #HIDDEN_END_fskr
 
-More details about attaching leads can be found in the tutorial
-:ref:`tutorial-abring`.
+This call returns the lead number which will be used to refer to the lead when
+computing transmissions (further down in this tutorial). More details about
+attaching leads can be found in the tutorial :ref:`tutorial-abring`.
 
 We also want to add a lead on the right side. The only difference to
 the left lead is that the vector of the translational
@@ -216,7 +217,9 @@ We use ``kwant.smatrix`` which is a short name for
 `kwant.solvers.default`.  ``kwant.smatrix`` computes the scattering matrix
 ``smatrix`` solving a sparse linear system.  ``smatrix`` itself allows to
 directly compute the total transmission probability from lead 0 to lead 1 as
-``smatrix.transmission(1, 0)``.
+``smatrix.transmission(1, 0)``. The numbering used to refer to the leads here
+is the same as the numbering assigned by the call to
+`kwant.builder.Builder.attach_lead` earlier in the tutorial.
 
 Finally we can use `matplotlib` to make a plot of the computed data
 (although writing to file and using an external viewer such as

kwant/builder.py

@@ -964,6 +964,8 @@ class Builder(object):
     def attach_lead(self, lead_builder, origin=None):
         """Attach a lead to the builder, possibly adding missing sites.
 
+        Returns the lead number (integer) of the attached lead.
+
         Parameters
         ----------
         lead_builder : `Builder` with 1D translational symmetry
@@ -984,6 +986,9 @@ class Builder(object):
         -----
         This method is not fool-proof, i.e. if it returns an error, there is
         no guarantee that the system stayed unaltered.
+
+        The lead numbering starts from zero and increments from there, i.e.
+        the leads are numbered in the order in which they are attached.
         """
         sym = lead_builder.symmetry
         H = lead_builder.H