From 3f653e20d27dda413c55e233d62eee505b47e8fd Mon Sep 17 00:00:00 2001
From: Pete Shadbolt <pete.shadbolt@gmail.com>
Date: Mon, 25 Jul 2016 01:10:22 +0100
Subject: [PATCH] Better docs

---
 abp/clifford.py | 51 +++++++++++++++++++++++++++++++++++++++++++++----
 doc/index.rst   |  4 +++-
 2 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/abp/clifford.py b/abp/clifford.py
index 5f9372c..33d3063 100644
--- a/abp/clifford.py
+++ b/abp/clifford.py
@@ -1,9 +1,43 @@
 # -*- coding: utf-8 -*-
 
 """
-This program generates and caches lookup tables, and handles the Clifford group.
-It provides tables for Clifford group multiplication and conjugation,
-as well as CZ and decompositions of the 2x2 Cliffords.
+This module handles operations on the Clifford group. It makes extensive use of the lookup tables in ``abp.tables``. 
+The code to generate those tables is included in this distribution as ``abp/build_tables.py``
+This package emumerates and labels the single-qubit Clifford group, and provides methods for matrix multiplication and conjugation.
+It also includes the look-up table for the CZ gate.
+
+There are 24 members of the single-qubit Clifford group. You can refer to some of them by multiple names.
+The complete set of aliases for single-qubit Cliffords is as follows:
+
+    ======= =========================
+    Index   Aliases
+    ======= =========================
+    0       ``IA, identity, identity_h``
+    1       ``px, XA, px_h``
+    2       ``py, YA, py_h``
+    3       ``pz, ZA, pz_h``
+    4       ``IB``
+    5       ``XB, sqz, msqz_h, phase_h``
+    6       ``YB, msqz, sqz_h, phase``
+    7       ``ZB``
+    8       ``IC``
+    9       ``XC, msqy, sqy_h``
+    10      ``YC, hadamard, hadamard_h``
+    11      ``ZC, sqy, msqy_h``
+    12      ``ID``
+    13      ``XD``
+    14      ``YD, sqx, msqx_h``
+    15      ``ZD, msqx, sqx_h``
+    16      ``IE``
+    17      ``XE``
+    18      ``YE``
+    19      ``ZE``
+    20      ``IF``
+    21      ``XF``
+    22      ``YF``
+    23      ``ZF``
+    ======= =========================
+
 """
 
 from tables import *
@@ -26,9 +60,18 @@ def human_name(i):
     choices = sorted((key for key, value in by_name.items() if value == i), key=len)
     return choices[-1]
 
-
 def is_diagonal(v):
     """ TODO: remove this. Checks if a VOP is diagonal or not """
     return v in {0, 3, 5, 6}
 
 
+if __name__ == '__main__':
+    from itertools import groupby
+
+    for i in range(24):
+        members = [key for key, value in by_name.items() if value == i and str(key)!=str(i)]
+        members = sorted(members, key=len)
+        print "* {}: {}".format(i, ", ".join(members))
+            
+
+
diff --git a/doc/index.rst b/doc/index.rst
index 0920514..411476f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -7,7 +7,7 @@
    :maxdepth: 2
 
 
-Welcome to ``abp``
+``abp``
 ===============================
 
 This is the documentation for ``abp``. It's a work in progress.
@@ -102,6 +102,8 @@ Here follows complete documentation
 The Clifford group
 ----------------------
 
+.. automodule:: abp.clifford
+
 Visualization
 ----------------------