Docs

.gitignore

@@ -25,3 +25,6 @@ pytac/#*
 
 # documentation
 docs/_build
+
+# jupyter
+.ipynb_checkpoints

README.md

@@ -2,6 +2,9 @@
 
 Python Toolkit for Accelerator Controls (Pytac) is a Python library intended to make it easy to work with particle accelerators.
 
+
+Documentation is available at [Readthedocs](http://pytac.readthedocs.io/en/latest/index.html).
+
 ## Testing
 
 It is simplest to work with a virtualenv.  Then:

docs/index.rst

@@ -1,20 +1,28 @@
-.. docs documentation master file, created by
-   sphinx-quickstart on Mon May  8 13:02:08 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.  include:: intro.rst
-
 Python Toolkit for Accelerator Controls
 =======================================
+
 Python Toolkit for Accelerator Controls (Pytac) is a Python library intended to make it easy to work with particle accelerators.
 
-It is a framework that implements high level configure/run behaviour of control system components.  Pytac  includes a set of API (Application Programming Interface) which is used for writing further scripts and interactive controls. The function of Pytac is to provide a scripting language for on-line control.
+It is a framework that allows working with control system components at a high level, providing a set of APIs used for writing further scripts and interactive controls.
 
+Two pieces of software influenced its design:
+
+* Matlab Middlelayer, used widely by accelerator physicists
+* APHLA, high-level applications written in Python by the NSLS-II accelerator physics group
 
 
 Software Overview
 =================
-Pytac provides a library of software that communicates with machine hardware for online applications. It is important to note that although the online get/set routines originally communicated via EPICS Channel Access they can now communicate with a variety of control systems. There are only two core functions that need to be re-programmed to work with the new control system - get and put inside the ControlSystem class.
 
+Pytac provides a Python library ``pytac`` that makes it easier to communicate with machine hardware for online applications. Although it currently works with EPICS, the `cs.ControlSystem` class may be sub-classed to allow other control systems to be used.
+
+The design is based around a ``Lattice`` object that contains a sequence of ``Element`` s.  Each element may have zero or more 'fields' (examples x, y, a1 or b2), associated with which are ``Device`` objects.  These devices contain the necessary information to request live data from the control system.
+
+Data may be requested in ``ENG`` or ``PHYS`` units and will be converted as appropriate.  Two types of unit conversion are available: Polynomial and Piecewise Cubic Hermite Interpolating Polynomial (Pchip).  Additional 
+
+Elements may be grouped into families (an element may be in more than one family) and requested from the lattice object in those families.
+
+Machines are defined using a set of ``.csv`` files, located by default in the ``data`` directory.
 
 
 Contents: