Started improving and updating the documentation.

6 files changed, 283 insertions, 14 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 0000000..1218881
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1,20 @@
+.. _contributing:
+
+Contributing to PyVISA
+======================
+
+You can contribute in different ways:
+
+Report issues
+-------------
+
+You can report any issues with the package, the documentation to the PyVISA `issue tracker`_. Also feel free to submit feature requests, comments or questions.
+
+
+Contribute code
+---------------
+
+To contribute fixes, code or documentation to PyVISA, send us a patch, or fork PyVISA in github_ and submit the changes using a pull request.
+
+.. _github: http://github.com/hgrecco/pyvisa
+.. _`issue tracker`: https://github.com/hgrecco/pyvisa/issues
diff --git a/docs/getting.rst b/docs/getting.rst
new file mode 100644
index 0000000..e00b2ca
--- /dev/null
+++ b/docs/getting.rst
@@ -0,0 +1,51 @@
+.. _getting:
+
+Installation
+============
+
+PyVISA has no dependencies except Python_ itself. In runs on Python 2.6+ and 3.2+.
+
+You can install it using pip_::
+
+    $ pip install pyvisa
+
+or using easy_install_::
+
+    $ easy_install pyvisa
+
+That's all! You can check that PyVISA is correctly installed by starting up python, and importing PyVISA:
+
+    >>> import visa
+
+.. note:: If you have an old system installation of Python and you don't want to
+   mess with it, you can try `Anaconda CE`_. It is a free Python distribution by
+   Continuum Analytics that includes many scientific packages.
+
+
+Getting the code
+----------------
+
+You can also get the code from PyPI_ or GitHub_. You can either clone the public repository::
+
+    $ git clone git://github.com/hgrecco/pyvisa.git
+
+Download the tarball::
+
+    $ curl -OL https://github.com/hgrecco/pyvisa/tarball/master
+
+Or, download the zipball::
+
+    $ curl -OL https://github.com/hgrecco/pyvisa/zipball/master
+
+Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily::
+
+    $ python setup.py install
+
+
+
+.. _easy_install: http://pypi.python.org/pypi/setuptools
+.. _Python: http://www.python.org/
+.. _pip: http://www.pip-installer.org/
+.. _`Anaconda CE`: https://store.continuum.io/cshop/anaconda
+.. _PyPI: https://pypi.python.org/pypi/PyVISA
+.. _GitHub: https://github.com/hgrecco/pyvisa
diff --git a/docs/index.rst b/docs/index.rst
index 03f48c4..a514d89 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,33 +18,38 @@ as easy as three lines of Python code::
 
     import visa
     keithley = visa.instrument("GPIB::12")
-    print keithley.ask("*IDN?")
+    print(keithley.ask("*IDN?"))
 
-(That's the whole program; really!) It is tailored to work on both Windows and
-Linux, and with arbitrary adapters (e.g. National Instruments, Agilent,
+(That's the whole program; really!) It is tailored to work on Windows,
+Linux and Mac; with arbitrary adapters (e.g. National Instruments, Agilent,
 Tektronix, Stanford Research Systems).  In order to achieve this, PyVISA
 relies on an external library file which is bundled with hardware and software
 of those vendors.  (So only in rare cases you have to purchase it separately.)
 
 PyVISA implements convenient and Pythonic programming in two layers:
 
-1. An object-oriented Python module has been created simply called ``visa``.
-   It is the recommended way to use PyVISA.  See the `PyVISA manual`_ for more
-   information.
-
-2. Additionally, there is the lower level module ``vpp43``, which directly
+1. A wrapper module around the visa library.
+   This module
+Additionally, there is the lower level module ``vpp43``, which directly
    calls the VISA functions from Python.  See the `PyVISA low-level
    implementation`_ for more information.  This is only for people who need
    full control or the official VISA functions for some reason.
 
+2. An object-oriented Python module has been created simply called ``visa``.
+   It is the recommended way to use PyVISA.  See the `PyVISA manual`_ for more
+   information.
+
+
 PyVISA is free open-source software.  The `PyVISA project page`_ contains the
 bug tracker and the download area.
 
 Projects using PyVISA so far:
 
-* `pyvLab`_ -- program to control VISA-talking instruments
+* `pyvLab`_ -- program to control VISA-talking instruments.
+* `Lantz`_ -- a Python instrumentation toolkit.
 
 .. _`pyvLab`: http://pyvlab.sourceforge.net/
+.. _`Lantz`: https://lantz.readthedocs.org/
 
 
 General overview
diff --git a/docs/migrating.rst b/docs/migrating.rst
new file mode 100644
index 0000000..ea98f2e
--- /dev/null
+++ b/docs/migrating.rst
@@ -0,0 +1,189 @@
+.. _migrating:
+
+Migrating from PyVISA < 1.5
+===========================
+
+You don't need to change anything in your code if you only use the `instrument`
+constructor; and attributes and methods of the resulting object.
+For example, this code will run unchanged in modern versions of PyVISA::
+
+    import visa
+    keithley = visa.instrument("GPIB::12")
+    print(keithley.ask("*IDN?"))
+
+This covers almost every single program that I have seen on the internet.
+However, if you use other parts of PyVISA or you are interested in the design
+decisions behind the new version you might want to read on.
+
+Some of these decisions were inspired by the `visalib` package as a part of `Lantz`
+
+
+Short summary
+-------------
+
+PyVISA 1.5 has full compatibility with previous versions of PyVISA. (changing some
+of the underlying implementation). But you are encouraged to do a few things
+differently if you want to keep up with the latest developments:
+
+If you are doing:
+
+    >>> import visa
+    >>> keithley = visa.instrument("GPIB::12")
+    >>> print(keithley.ask("*IDN?"))
+
+change it to:
+
+    >>> import visa
+    >>> rm = visa.ResourceManager()
+    >>> keithley = rm.instrument("GPIB::12")
+    >>> print(keithley.ask("*IDN?"))
+
+If you are doing
+
+    >>> print(visa.get_instruments_list())
+
+change it to:
+
+    >>> print(rm.list_resources())
+
+If you were using::
+
+    >>> import pyvisa.vpp43 as vpp43
+    >>> vpp43.visa_library.load_library("/path/to/my/libvisa.so.7")
+
+change it to::
+
+    >>> import visa
+    >>> lib = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+
+
+If you were using::
+
+    >>> vpp43.lock(session)
+
+change it to::
+
+    >>> lib.lock(session)
+
+
+As you see, most of the code shown above is above making a few things explict.
+It adds 1 line of code (instantiating the VisaLibrary or ResourceManager object)
+which is not a big deal but it makes things cleaner.
+
+If you were using `printf`, `queryf`, `scanf`, `sprintf` or `sscanf` of `vpp43`,
+rewrite as pure python code.
+
+
+Isolated low-level wrapping module
+----------------------------------
+
+In the original PyVISA implementation, the low level implementation (`vpp43`) was
+mixed with higher level constructs such as `VisaLibrary`, `VisaException` and error
+messages. The VISA library was wrapped using ctypes.
+
+In 1.5, we refactored it as `ctwrapper`, also a ctypes wrapper module but it only
+depends on the constants definitions (`constants.py`). This allow us to test the
+foreign function calls by isolating them from higher level abstractions. More importantly,
+it also allow us to build new low level modules that can used as drop in replacements
+for `ctwrapper` in high level modules.
+
+We have two modules planned:
+- a Mock module that allows you to test a PyVISA program even if you do not have
+  VISA installed.
+- a CFFI based wrapper. CFFI is new python package that allows easier and more
+  robust wrapping of foreign libraries. It might be part of Python in the future.
+
+PyVISA 1.5 keeps `vpp43` (reimplemented on top of `ctwrapper`) for backwards
+compatibility but will be removed in future versions.
+
+All functions that were present in `vpp43` are now present in `ctwrapper` but they
+take an additional first parameter: the foreign library wrapper.
+
+We suggest that you replace `vpp43` by using the new VisaLibrary object which provides
+all foreign functions as bound methods (see below).
+
+
+Dropped support for string related functions
+--------------------------------------------
+
+The VISA library includes functions to search and manipulte strings such as `printf`,
+`queryf`, `scanf`, `sprintf` and `sscanf`. This makes sense as visa involves a lot of
+string handling operations. The original PyVISA implementation wrapped these functions.
+But these operations are easily expressed in pure python and therefore were rarely used.
+
+PyVISA 1.5 keeps these functions for backwards compatibility but it will be removed in 1.6.
+
+We suggest that you replace such functions by pure python version.
+
+
+No singleton objects
+--------------------
+
+The original PyVISA implementation relied on a singleton, global objects for the
+library wrapper (named `visa_library`, an instance of the old `pyvisa.vpp43.VisaLibrary`)
+and the resource manager (named `resource_manager`, and instance of the old
+`pyvisa.visa.ResourceManager`). These were instantiated on import and the user
+could rebind to a different library usingthe `load_library` method. Calling this
+method however did not affected `resource_manager` and might lead to an insconsistent
+state.
+
+In 1.5, there is a new `VisaLibrary` class and a new `ResourceManager` class (they are
+both in `pyvisa.highlevel`). The new classes are not singletons, at least not in the
+strict sense. Multiple instances of `VisaLibrary` and `ResourceManager` are possible,
+but only if they refer to different foreign libraries. In code, this means:
+
+    >>> lib1 = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> lib2 = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> lib3 = visa.VisaLibrary("/path/to/my/libvisa.so.8")
+    >>> lib1 is lib2
+    True
+    >>> lib1 is lib3
+    False
+
+Most of the time, you will not need access to a `VisaLibrary` object but to a `ResourceManager`.
+You can do:
+
+    >>> lib = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> rm = lib.resource_manager
+
+or equivanlently:
+
+    >>> rm = visa.ResourceManager("/path/to/my/libvisa.so.7")
+
+.. note:: If the path for the library is not given, the path is obtained from
+          the user settings file (if exists) or guessed from the OS.
+
+You can still access the legacy classes and global objects::
+
+    >>> from pyvisa.legacy import vpp43
+    >>> from pyvisa.legacy import VisaLibrary
+    >>> from pyvisa.legacy import `visa_library` and `resource_manager`
+
+In 1.5, `visa_library` and `resource_manager`, instances of the legacy classes,
+will be instantiated on import. In 1.6+ you will need to manually instantiate
+these classes.
+
+
+VisaLibrary methods as way to call Visa functions
+-------------------------------------------------
+
+In the original PyVISA implementation, the `VisaLibrary` class was just having
+a reference to the ctypes library and a few functions.
+
+In 1.5, we introduced a new `VisaLibrary` class (`pyvisa.highlevel`) which has as
+bound methods every single low level function defined in `ctwrapper`. In code, this
+means that you can do::
+
+    >>> import visa
+    >>> lib = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> print(lib.read_stb(session))
+
+It also has every single VISA foreign function in the underlying library as static
+method. In code, this means that you can do::
+
+    >>> lib = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> status = ctypes.c_ushort()
+    >>> ret library.viReadSTB(session, ctypes.byref(status))
+    >>> print(ret.value)
+
+
diff --git a/docs/pyvisa.rst b/docs/pyvisa.rst
index 7c3b2db..c75ec47 100644
--- a/docs/pyvisa.rst
+++ b/docs/pyvisa.rst
@@ -64,7 +64,7 @@ display at the moment?"::
 

 Finally, I print the instrument's answer on the screen: ::

 

-   print my_instrument.read()

+   print(my_instrument.read())

 

 

 Example for serial (RS232) device

@@ -83,7 +83,7 @@ following code prints its self-identification on the screen::
    

    itc4 = instrument("COM2")

    itc4.write("V")

-   print itc4.read()

+   print(itc4.read())

 

 .. index:: single: instrument()

 

@@ -93,7 +93,7 @@ one `ask()` call.  Thus, the above source code is equivalent to::
    from visa import *

    

    itc4 = instrument("COM2")

-   print itc4.ask("V")

+   print(itc4.ask("V"))

 

 It couldn't be simpler.  See section :ref:`sec:serial-devices` for

 further information about serial devices.

diff --git a/docs/vpp43.rst b/docs/vpp43.rst
index 483032d..11af968 100644
--- a/docs/vpp43.rst
+++ b/docs/vpp43.rst
@@ -1,8 +1,12 @@
 .. _vpp43:
 
 
-About the vpp43 module
-======================
+.. note:: This is a legacy module kept for backwards compatiblity with PyVISA < 1.5.
+          The functionality in this module is now implemented in the `wrapper` module.
+
+
+About the legacy vpp43 module
+=============================
 
 This module ``vpp43`` is a cautious yet thorough adaption of the VISA
 specification for Python.  The "textual languages" VISA specification can't be