Merge pull request #43 from willrogers/docs

Tweaks to documentation and readme.

README.rst

@@ -12,7 +12,7 @@
    :target: https://badge.fury.io/py/pytac
 
 
-Python Toolkit for Accelerator Controls (Pytac) is a Python library intended to make it easy to work with particle accelerators.
+Python Toolkit for Accelerator Controls (Pytac) is a Python library for working with elements of particle accelerators.
 
 Documentation is available at Readthedocs_.
 
@@ -24,14 +24,13 @@ Testing
 It is simplest to work with a virtualenv.  Then::
 
  $ pip install -r requirements/local.txt
- $ export PYTHONPATH=.
- $ py.test test
+ $ python -m pytest test
 
 To see a coverage report::
 
- $ py.test --cov=pytac test
+ $ python -m pytest --cov=pytac test
 
-To build documentation correctly::
+To build the documentation::
 
  $ cd docs
  $ sphinx-build -b html -E . _build/html
@@ -40,7 +39,8 @@ The documentation is built inside _build/html.
 
 Uploading to Pypi
 =================
-To upload files to Pypi. Create a source distribution::
+
+Create a source distribution::
 
  $ python setup.py sdist
 

docs/examples.rst

@@ -5,21 +5,31 @@ Examples
 Initialisation
 ~~~~~~~~~~~~~~
 
-- Import 'pytac' and initialise the ``VMX`` ring mode:
+- Install pytac and cothread for EPICS support, and start Python::
 
-     >>> import pytac.load_csv
-     >>> lattice = pytac.load_csv.load('VMX')
+    $ pip install pytac
+    $ pip install cothread
+    $ 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.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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Get elements representing BPMs:
+- Get elements representing BPMs::
 
     >>> bpms = lattice.get_elements('BPM')
 
-- Print the device names and s position of each BPM:
+- Print the device names and s position of each BPM::
 
     >>> for bpm in bpms:
     >>>    print('BPM {} at position {}'.format(bpm.get_device('x').name, lattice.get_s(bpm)))
@@ -30,7 +40,7 @@ Print BPM pvs along with s position
     BPM SR01C-DI-EBPM-05 at position 14.9425
     ...
 
-- Get PV names and positions for BPMs directly from the lattice object:
+- Get PV names and positions for BPMs directly from the lattice object::
 
     >>> lattice.get_pv_names('BPM', 'x', pytac.RB)
     ['SR01C-DI-EBPM-01:SA:X',
@@ -51,7 +61,7 @@ Print BPM pvs along with s position
 Get the pv value from the quad elements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Get the Quad elements and print their readback values on the b1 field:
+- Get the Quad elements and print their readback values on the b1 field::
 
     >>> quads = lattice.get_elements('QUAD')
     >>> for quad in quads:
@@ -63,7 +73,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
-  since it uses only one request to the control system:
+  since it uses only one request to the control system::
 
     >>> lattice.get_pv_values('QUAD', 'b1', pytac.RB)
     [71.32496643066406,

docs/index.rst

@@ -3,7 +3,7 @@ Python Toolkit for Accelerator Controls
 
 Python Toolkit for Accelerator Controls (Pytac) is a Python library for working with elements of particle accelerators.
 
-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.
+It is hosted on Github at https://github.com/willrogers/pytac.
 
 Two pieces of software influenced its design:
 

pytac/load_csv.py

@@ -1,4 +1,6 @@
 """Module to load the elements of the machine from multiple csv files stored in the same directory."""
+from __future__ import print_function
+import sys
 import os
 import csv
 from pytac import lattice, element, device, units, utils
@@ -72,13 +74,20 @@ def load(mode, control_system=None, directory=None):
     Returns:
         Lattice: The lattice containing all elements.
     """
-    if control_system is None:
-        # Don't import epics unless we need it to avoid unnecessary
-        # installation of cothread
-        from pytac import epics
-        control_system = epics.EpicsControlSystem()
+    try:
+        if control_system is None:
+            # Don't import epics unless we need it to avoid unnecessary
+            # installation of cothread
+            from pytac import epics
+            control_system = epics.EpicsControlSystem()
+    except ImportError:
+        print(('To load a lattice using the default control system,'
+                ' please install cothread.'),
+              file=sys.stderr)
+        return None
     if directory is None:
-        directory = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'data')
+        directory = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                 'data')
     lat = lattice.Lattice(mode, control_system, 3000)
     with open(os.path.join(directory, mode, 'elements.csv')) as elements:
         csv_reader = csv.DictReader(elements)