Build docs with warnings as errors

.travis.yml

@@ -24,6 +24,9 @@ install:
     - pip install -r requirements.txt
     - pip install -r test_requirements.txt --upgrade
     - pip install -r docs_requirements.txt
+# Install a new version of Sphinx that correctly handles forward refs once 1.7.0 is out that should
+# be used instead
+    - pip install git+https://github.com/jenshnielsen/sphinx.git@working_forward_ref --upgrade
     - pip install -e .
 
 before_script: # configure a headless display to test plot generation
@@ -36,7 +39,7 @@ script:
     - py.test --cov=qcodes --cov-report xml --cov-config=.coveragerc
     - |
       cd ../docs
-      make html-api
+      make SPHINXOPTS="-W" html-api
     - cd ..
 
 after_success:

docs/Makefile

@@ -228,8 +228,9 @@ dummy:
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
 
+.PHONY: html-api
 html-api:
-	sphinx-apidoc  -o  _auto  -d 10 ../qcodes/ ../qcodes/instrument_drivers/Spectrum/pyspcm.py  ../qcodes/instrument_drivers/Spectrum/py_header/h2py.py
+	sphinx-apidoc  -o  _auto  -d 10 ../qcodes/ ../qcodes/instrument_drivers/Spectrum/pyspcm.py ../qcodes/instrument_drivers/Spectrum/M4i.py ../qcodes/instrument_drivers/keysight
 	mkdir -p api/generated/
 	mkdir -p _notebooks
 	mkdir -p _notebooks/driver_examples
@@ -240,6 +241,7 @@ html-api:
 	jupyter-nbconvert --to rst 'examples/benchmarking/*.ipynb' --output-dir=_notebooks/benchmarking
 	make html
 
+.PHONY: gh-pages
 gh-pages:
 	git config --global user.email "bot@travics.com"
 	git config --global user.name "Documentation Bot"

docs/conf.py

@@ -67,7 +67,9 @@
 copyright = '2016, Giulio Ungaretti, Alex Johnson'
 author = 'Giulio Ungaretti, Alex Johnson'
 
-
+# Import matplotlib before qcodes import pyplot to set the backend
+import matplotlib
+matplotlib.use('Agg')
 # auto versioning
 import qcodes
 version = '{}'.format(qcodes.__version__)
@@ -376,12 +378,6 @@
 autodoc_default_flags = []
 # we have to do this, do avoid sideeffects when importing matplotlib
 autodoc_mock_imports = []
-try:
-    import matplotlib
-    matplotlib.use('PS')
-    autodoc_mock_imports.append('matplotlib')
-except ImportError as e:
-        print(e)
 autodoc_mock_imports.append('pyspcm')
 autodoc_mock_imports.append('zhinst')
 autodoc_mock_imports.append('zhinst.utils')

docs/examples/Datasaving examples.ipynb

@@ -9,7 +9,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -21,7 +21,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -45,7 +45,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -63,7 +63,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -72,52 +72,21 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "root - WARNING - Error getting or interpreting *IDN?: ''\n"
-     ]
-    },
-    {
-     "data": {
-      "text/plain": [
-       "'MockParabola'"
-      ]
-     },
-     "execution_count": 5,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
    "source": [
     "from qcodes.tests.instrument_mocks import MockParabola\n",
     "station.add_component(MockParabola(name='MockParabola', server_name=None))"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "metadata": {
     "scrolled": false
    },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "DataSet:\n",
-      "   location = 'data/2017-03-10/#017_MockParabola_run_15-44-02'\n",
-      "   <Type>   | <array_id>                   | <array.name>    | <array.shape>\n",
-      "   Setpoint | MockParabola_x_set           | x               | (10,)\n",
-      "   Measured | MockParabola_skewed_parabola | skewed_parabola | (10,)\n",
-      "started at 2017-03-10 15:44:02\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "loop = qc.Loop(station.MockParabola.x[-100:100:20]).each(station.MockParabola.skewed_parabola)\n",
     "data_l = loop.run(name='MockParabola_run', formatter=qc.data.gnuplot_format.GNUPlotFormat())\n",
@@ -126,23 +95,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "DataSet:\n",
-      "   location = 'data/2017-03-10/#018_MockParabola_run_15-44-07'\n",
-      "   <Type>   | <array_id>                   | <array.name>    | <array.shape>\n",
-      "   Setpoint | MockParabola_x_set           | x               | (10,)\n",
-      "   Setpoint | MockParabola_y_set           | y               | (10, 15)\n",
-      "   Measured | MockParabola_skewed_parabola | skewed_parabola | (10, 15)\n",
-      "started at 2017-03-10 15:44:07\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "reload(hdf5_format)\n",
     "h5fmt = hdf5_format.HDF5Format()\n",
@@ -153,7 +108,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -174,78 +129,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": null,
    "metadata": {
     "scrolled": false
    },
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "test_closed_file (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... root - WARNING - Cannot close file, data_set has no open hdf5 file\n",
-      "root - WARNING - Cannot close file, data_set has no open hdf5 file\n",
-      "ok\n",
-      "test_dataset_closing (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_dataset_finalize_closes_file (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_dataset_flush_after_write (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_dataset_with_missing_attrs (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_double_closing_gives_warning (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_full_write_read_1D (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_full_write_read_2D (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_incremental_write (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_loop_writing (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... root - WARNING - Error getting or interpreting *IDN?: ''\n",
-      "ok\n",
-      "test_loop_writing_2D (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... root - WARNING - Error getting or interpreting *IDN?: ''\n",
-      "ok\n",
-      "test_metadata_write_read (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_read_writing_dicts_withlists_to_hdf5 (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_reading_into_existing_data_array (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_str_to_bool (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_writing_metadata (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... ok\n",
-      "test_writing_unsupported_types_to_hdf5 (qcodes.tests.test_hdf5formatter.TestHDF5_Format) ... root - WARNING - List of type \"<class 'qcodes.data.data_set.DataSet'>\" for \"list_of_dataset\":\"[DataSet:\n",
-      "   location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#016_test_missing_attr_15-44-09'\n",
-      "   <Type> | <array_id> | <array.name> | <array.shape>, DataSet:\n",
-      "   location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#016_test_missing_attr_15-44-09'\n",
-      "   <Type> | <array_id> | <array.name> | <array.shape>]\" not supported, storing as string\n",
-      "root - WARNING - Type \"<class 'qcodes.data.data_set.DataSet'>\" for \"nested_dataset\":\"DataSet:\n",
-      "   location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#016_test_missing_attr_15-44-09'\n",
-      "   <Type> | <array_id> | <array.name> | <array.shape>\" not supported, storing as string\n",
-      "root - WARNING - List of mixed type for \"<class 'list'>\":\"list_of_mixed_type\" not supported, storing as string\n"
-     ]
-    },
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "DataSet:\n",
-      "   location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#010_MockLoop_hdf5_test_15-44-09'\n",
-      "   <Type>   | <array_id>                        | <array.name>    | <array.shape>\n",
-      "   Setpoint | Loop_writing_test_x_set           | x               | (10,)\n",
-      "   Measured | Loop_writing_test_skewed_parabola | skewed_parabola | (10,)\n",
-      "started at 2017-03-10 15:44:09\n",
-      "DataSet:\n",
-      "   location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#011_MockLoop_hdf5_test_15-44-09'\n",
-      "   <Type>   | <array_id>                           | <array.name>    | <array.shape>\n",
-      "   Setpoint | Loop_writing_test_2D_x_set           | x               | (10,)\n",
-      "   Setpoint | Loop_writing_test_2D_y_set           | y               | (10, 10)\n",
-      "   Measured | Loop_writing_test_2D_skewed_parabola | skewed_parabola | (10, 10)\n",
-      "started at 2017-03-10 15:44:09\n"
-     ]
-    },
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "ok\n",
-      "\n",
-      "----------------------------------------------------------------------\n",
-      "Ran 17 tests in 0.348s\n",
-      "\n",
-      "OK\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "from qcodes.utils import helpers\n",
     "reload(helpers)\n",
@@ -262,9 +150,21 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
    "outputs": [],
    "source": []
   }
@@ -285,7 +185,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.3"
+   "version": "3.6.2"
   },
   "widgets": {
    "state": {},

docs/examples/Tutorial.ipynb

@@ -37,19 +37,11 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {
     "scrolled": false
    },
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "User schema at /Users/jhn/qcodesrc_schema.json not found.User settings won't be validated\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# usually, one imports QCoDeS and some instruments\n",
     "import qcodes as qc\n",
@@ -355,9 +347,10 @@
    "metadata": {},
    "source": [
     "#### Output of the loop\n",
-    "A loop returns a dataset.  \n",
-    "The representation of the dataset shows what arrays it contains and where it is saved.   \n",
-    "The dataset initially starts out empty (filled with NAN's) and get's filled while the Loop get's executed. "
+    "\n",
+    "* A loop returns a dataset.\n",
+    "* The representation of the dataset shows what arrays it contains and where it is saved.\n",
+    "* The dataset initially starts out empty (filled with NAN's) and get's filled while the Loop get's executed."
    ]
   },
   {
@@ -584,7 +577,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.3"
+   "version": "3.6.2"
   }
  },
  "nbformat": 4,

qcodes/instrument/parameter.py

@@ -15,11 +15,13 @@
 
 - ``Parameter`` is the base class for scalar-valued parameters.
     Two primary ways in which it can be used:
+
     1. As an ``Instrument`` parameter that sends/receives commands. Provides a
        standardized interface to construct strings to pass to the
        instrument's ``write`` and ``ask`` methods
     2. As a variable that stores and returns a value. For instance, for storing
        of values you want to keep track of but cannot set or get electronically.
+
     Provides ``sweep`` and ``__getitem__`` (slice notation) methods to use a
     settable parameter as the swept variable in a ``Loop``.
     The get/set functionality can be modified.
@@ -627,12 +629,15 @@ class Parameter(_BaseParameter):
 
     By default only gettable, returning its last value.
     This behaviour can be modified in two ways:
+
     1. Providing a ``get_cmd``/``set_cmd``, which can of the following:
+
        a. callable, with zero args for get_cmd, one arg for set_cmd
        b. VISA command string
        c. None, in which case it retrieves its last value for ``get_cmd``,
           and stores a value for ``set_cmd``
        d. False, in which case trying to get/set will raise an error.
+
     2. Creating a subclass with an explicit ``get``/``set`` method. This
        enables more advanced functionality.