# HG changeset patch
# User Brian Neal <bgneal@gmail.com>
# Date 1374199776 18000
# Node ID 42d7e5410dbd0afc9d65b51f8ea732c473c3612c
# Parent  35b5eb90f5adfa845f0314eb93cf8b4843f6b05f
Started the library docs. Added some docs for KeyList.

diff -r 35b5eb90f5ad -r 42d7e5410dbd docs/index.rst
--- a/docs/index.rst	Fri Jul 12 14:32:51 2013 -0500
+++ b/docs/index.rst	Thu Jul 18 21:09:36 2013 -0500
@@ -42,10 +42,11 @@
 Contents:
 
 .. toctree::
+   :maxdepth: 3
+
    tutorial
    commandline
    library
-   :maxdepth: 2
 
 
 Requirements
diff -r 35b5eb90f5ad -r 42d7e5410dbd docs/library.rst
--- a/docs/library.rst	Fri Jul 12 14:32:51 2013 -0500
+++ b/docs/library.rst	Thu Jul 18 21:09:36 2013 -0500
@@ -1,2 +1,94 @@
 Library Reference
 =================
+
+This section of the documentation is aimed at developers who wish to use the
+``m209`` library as part of their own application. This documentation covers
+the major classes and functions.
+
+Key lists
+---------
+
+Key lists are represented as a named tuple called ``KeyList``.
+
+.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)
+
+   As a named tuple, ``KeyList`` has the following attributes:
+
+   * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
+     the range ``AA`` - ``ZZ``
+   * ``lugs`` - a string representing the drum lug settings; see below
+   * ``pin_list`` - a list of six strings which represent key wheel pin
+     settings; see below
+   * ``letter_check`` - a string representing the letter check used to verify
+     operator settings; if unknown this can be ``None`` or an empty string
+   
+Lug settings string format
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Drum lug settings are often conveniently represented as strings consisting of
+at most 27 whitespace-separated pairs of integers separated by dashes. For
+example::
+
+   lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'
+
+Each integer pair must be in the form ``m-n`` where m & n are integers
+between 0 and 6, inclusive. Each integer represents a lug position where
+0 is a neutral position, and 1-6 correspond to key wheel positions. If
+m & n are both non-zero, they cannot be equal.
+
+If a string has less than 27 pairs, it is assumed all remaining bars have both
+lugs in the neutral (0) positions.
+
+Order of the pairs within the string does not matter.
+
+To reduce typing and to aid in readability, an alternate shortcut notation is
+supported::
+
+   lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'
+
+Any pair that is suffixed by ``*k``, where k is a positive integer, means there
+are ``k`` copies of the preceeding lug pair combination. For example, these two
+strings describe identical drum configurations::
+
+   lugs1 = '2-4 2-4 2-4 0-1 0-1'
+   lugs2 = '2-4*3 0-1*2'
+
+Key wheel pin settings
+~~~~~~~~~~~~~~~~~~~~~~
+
+Key wheel pin settings are represented as iterables of letters whose pins are
+slid to the "effective" position (to the right). Letters not appearing in this
+sequence are considered to be in the "ineffective" position (to the left). If
+None or empty, all pins are set to be ineffective.
+
+Examples::
+
+   all_ineffective = ''
+   wheel1 = 'ABDEFHIJMQSUXZ'
+   wheel2 = 'EINPQRTVXZ'
+   wheel3 = 'DEFGIKNOSUX'
+   wheel4 = 'BFGJKRS'
+   wheel5 = 'ABCDFGHIJMPS'
+   wheel6 = 'ADEFHIJKN'
+
+Key List Example
+~~~~~~~~~~~~~~~~
+
+An example of using the :py:class:`m209.keylist.KeyList` is:
+
+.. code-block:: python
+
+   from m209.keylist import KeyList
+
+   key_list1 = KeyList(
+          indicator='AA',
+          lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6',
+          pin_list=[
+              'FGIKOPRSUVWYZ',
+              'DFGKLMOTUY',
+              'ADEFGIORTUVX',
+              'ACFGHILMRSU',
+              'BCDEFJKLPS',
+              'EFGHIJLMNP'
+          ],
+          letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')