Documentation changes

docs/examples.rst

@@ -2,30 +2,48 @@
 Examples
 ========
 
-Initialisation
-~~~~~~~~~~~~~~
+Installation
+~~~~~~~~~~~~
+
+This is only required on your first use.
+
+- Ensure you have the following requirements: Pip, Pipenv, and a local copy of pytac.
 
-- Install pytac and cothread for EPICS support, and start Python::
+- Install dev-packages, pytac, and cothread for EPICS support::
 
+    $ pipenv install --dev
     $ pip install pytac
     $ pip install cothread
+
+
+Initialisation
+~~~~~~~~~~~~~~
+
+This is required each time you want to start up pytac.
+
+- Navigate to your pytac directory and activate a Pipenv shell, and start Python::
+
+    $ cd <directory-path>
+    $ pipenv shell
     $ python
     Python 2.7.3 (default, Nov  9 2013, 21:59:00)
     [GCC 4.4.7 20120313 (Red Hat 4.4.7-3)] on linux2
     Type "help", "copyright", "credits" or "license" for more information.
     >>>
 
-- Import 'pytac' and initialise the ``VMX`` ring mode::
+
+- Import pytac and initialise the ``VMX`` ring mode::
 
     >>> import pytac.load_csv
     >>> lattice = pytac.load_csv.load('VMX')
 
+
 The ``lattice`` object is used for interacting with elements of the accelerator.
 
-Print BPM pvs along with s position
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Print BPM pv names along with s position
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Get elements representing BPMs::
+- Get all elements that represent BPMs::
 
     >>> bpms = lattice.get_elements('BPM')
 
@@ -58,10 +76,10 @@ Print BPM pvs along with s position
      11.374000000000002,
      ...
 
-Get the pv value from the quad elements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Get the value of the 'b1' field of the quad elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Get the Quad elements and print their readback values on the b1 field::
+- Get all Quadrupole elements and print their 'b1' field read back values::
 
     >>> quads = lattice.get_elements('QUAD')
     >>> for quad in quads:
@@ -72,7 +90,7 @@ Get the pv value from the quad elements
     ...
 
 
-- Print the quad pv values on the b1 field using the lattice. This is more efficient
+- Print the quad read back values of the b1 field using the lattice. This is more efficient
   since it uses only one request to the control system::
 
     >>> lattice.get_values('QUAD', 'b1', pytac.RB)

docs/index.rst

@@ -16,11 +16,11 @@ Overview
 
 Pytac provides a Python library ``pytac`` that makes it easier to communicate with machine hardware for online applications. Although it currently works with EPICS, it should be possible to adapt to support other control systems.
 
-The design is based around a ``Lattice`` object that contains a sequence of ``Element`` s.  Each element represents a physical component in accelerator, such as an electromagnet, drift or BPM. For control purposes, each element may have zero or more 'fields' that represent parameters that may change: a BPM element has fields 'x' and 'y' that represent beam position, and a quadrupole magnet has 'b1' that represents the quadrupolar magnetic field. For monitoring and controlling these fields, elements have one ``Device`` object per field.  These devices contain the necessary information to get and set live data using the control system.
+The design is based around a ``Lattice`` object that contains a sequence of ``Element`` s. Each element represents a physical component in the accelerator, such as an electromagnet, drift, or BPM. Each element may have zero or more 'fields', each representing a parameter of the component that may change e.g. a BPM element has fields 'x' and 'y' that represent the beam position, and a quadrupole magnet has 'b1' that represents the quadrupolar magnetic field. Each field has one ``Device`` object for monitoring and control purposes, these devices contain the necessary information to get and set parameter data using 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 (often used for linear conversion) and Piecewise Cubic Hermite Interpolating Polynomial (Pchip; often used for magnet data where field may not be linear with current).  In the case that measurement data (used to set up the conversion objects) is not in the same units as the physical models, further functions may be given to these objects to complete the conversion correctly.
+Elements may be grouped into families (an element may be in more than one family), and requested from the lattice object in those families. Some methods take 'handle' inputs, handles specify whether the request made to the IOC pv is a get (read back-'pytac.RB') or set (set point-'pytac.SP') request.
 
-Elements may be grouped into families (an element may be in more than one family) and requested from the lattice object in those families.
+Data may be requested in ``ENG`` or ``PHYS`` units and will be converted as appropriate.  Two types of unit conversion are available: Polynomial (often used for linear conversion) and Piecewise Cubic Hermite Interpolating Polynomial (Pchip; often used for magnet data where field may not be linear with current).  In the case that measurement data (used to set up the conversion objects) is not in the same units as the physical models, further functions may be given to these objects to complete the conversion correctly.
 
 Machines are defined using a set of ``.csv`` files, located by default in the ``pytac/data`` directory.
 

docs/pytac.rst

@@ -61,3 +61,11 @@ pytac.units module
     :members:
     :undoc-members:
     :show-inheritance:
+
+pytac.utils module
+------------------
+
+.. automodule:: pytac.utils
+    :members:
+    :undoc-members:
+    :show-inheritance: