Add tutorial and doctest.

Author: t-sommer

README.rst

@@ -4,38 +4,77 @@ Scientific Data Format for Python
 =================================
 
 SDF is a Python package to read, write and interpolate multi-dimensional data.
-The Scientific Data Format is an open file format based on HDF5 to store
-multi-dimensional data such as parameters, simulations results or measurements.
+The Scientific Data Format is an open file format based on HDF5_ to store
+multi-dimensional data such as parameters, simulation results or measurements.
 It supports...
 
 - very large files
 - up to 32 dimensions
 - hierarchical structure
 - units, comments and custom meta-information
 
-For detailed information see the SDF specification.
+For detailed information see the `SDF specification`_.
 
 
 Installation
 ------------
 
-Install the latest release from PyPI
+Install the latest release from PyPI::
 
-::
+    $ pip install sdf
 
-    $ sudo pip install sdf
-
-or install the latest development version from source
-
-::
+or install the latest development version from source::
 
     $ git clone --branch develop --recursive https://github.com/ScientificDataFormat/SDF-Python.git
     $ cd SDF-Python
-    $ sudo pip install .
+    $ pip install .
+
+
+Tutorial
+--------
+
+Import the ``SDF`` and ``NumPy`` packages:
+
+    >>> import sdf
+    >>> import numpy as np
+
+Create the data arrays:
+
+    >>> t = np.linspace(0, 10, 51)
+    >>> v = np.sin(t)
+
+Create the datasets:
+
+    >>> ds_t = sdf.Dataset('t', data=t, unit='s', is_scale=True, display_name='Time')
+    >>> ds_v = sdf.Dataset('v', data=v, unit='V', scales=[ds_t])
+
+Create the root group and write the file:
+
+    >>> g = sdf.Group('/', comment='A sine voltage', datasets=[ds_t, ds_v])
+    >>> sdf.save('sine.sdf', g)
+
+Read the dataset from the SDF file asserting the correct unit of the dataset and scale:
+
+    >>> ds_v2 = sdf.load('sine.sdf', '/v', unit='V', scale_units=['s'])
+
+Get the meta info and data array from the dataset:
+
+    >>> ds_v2.unit
+    'V'
+    >>> ds_v2.data.shape
+    (51,)
+
+Get the scale for the first dimension:
+
+    >>> ds_t2 = ds_v2.scales[0]
+    >>> ds_t2.unit
+    's'
 
 
 -----------------------------
 
 |copy| 2017 Dassault Systèmes
 
+.. _SDF specification: https://github.com/ScientificDataFormat/SDF-Specification
+.. _HDF5: https://www.hdfgroup.org/hdf5/
 .. |copy|   unicode:: U+000A9

appveyor.yml

@@ -13,7 +13,7 @@ init:
   - "echo %PYTHON_VERSION% %MINICONDA%"
 
 install:
-  - cmd: git submodule update --init --recursive
+  - git submodule update --init --recursive
   - "set PATH=%MINICONDA%;%MINICONDA%\\Scripts;%PATH%"
   - conda config --set always_yes yes --set changeps1 no
   - conda update -q conda
@@ -23,6 +23,7 @@ install:
   - pip install dymat
 
 test_script:
+  - python -m doctest README.rst
   - build_windows
   - pip install .
   - cd tests