From b9ab98dea660a033bea5baa9992e4815215126c3 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Wed, 6 Dec 2017 11:38:45 +0100 Subject: [PATCH] Build docs with warnings as errors (#882) * set matplotlib backend in a way that works * parameter correct rst syntax * also ignore M4i file since the import breaks in docs build * Change filenames to fix missing images due to https://github.com/ipython/ipython/issues/5350 * Strip invalid output * Add missing phony * Build docs with sphinx warnings as errors * dont treat warnings as errors * exclude the wrong keysight dir * try to fix issue in tutorial * Revert "dont treat warnings as errors" This reverts commit e8367b970fbb5164462f3a9ddd608706f5d7dcab. * add title * Better name * make sure that autogen api is removed too --- .travis.yml | 5 +- docs/Makefile | 5 +- docs/conf.py | 10 +- docs/examples/Datasaving examples.ipynb | 158 ++++-------------- docs/examples/Tutorial.ipynb | 21 +-- ... Qcodes example with Yokogawa GS2xx.ipynb} | 9 +- ...ipynb => Qcodes_example_with_AMI430.ipynb} | 0 ...pynb => Qcodes_example_with_HP8753D.ipynb} | 0 ...ith_Keysight_Infiniium_Oscilloscope.ipynb} | 0 qcodes/instrument/parameter.py | 5 + 10 files changed, 60 insertions(+), 153 deletions(-) rename docs/examples/driver_examples/{Qcodes example with Yokogawa.ipynb => Qcodes example with Yokogawa GS2xx.ipynb} (98%) rename docs/examples/driver_examples/{Qcodes example with AMI430.ipynb => Qcodes_example_with_AMI430.ipynb} (100%) rename docs/examples/driver_examples/{Qcodes example with HP8753D.ipynb => Qcodes_example_with_HP8753D.ipynb} (100%) rename docs/examples/driver_examples/{Qcodes example with Keysight Infiniium Oscilloscope.ipynb => Qcodes_example_with_Keysight_Infiniium_Oscilloscope.ipynb} (100%) diff --git a/.travis.yml b/.travis.yml index 41dcc9daace..2c9e622ee0f 100644 --- a/.travis.yml +++ b/.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: diff --git a/docs/Makefile b/docs/Makefile index 33174254824..c4230a01ab4 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -51,6 +51,7 @@ clean: rm -rf $(BUILDDIR)/* rm -rf _auto rm -rf _notebooks + rm -rf api/generated .PHONY: html html: @@ -228,8 +229,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 +242,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" diff --git a/docs/conf.py b/docs/conf.py index 71c1b67599b..a4b0dde5fba 100644 --- a/docs/conf.py +++ b/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') diff --git a/docs/examples/Datasaving examples.ipynb b/docs/examples/Datasaving examples.ipynb index 6aba21f895f..23846fc015f 100644 --- a/docs/examples/Datasaving examples.ipynb +++ b/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,27 +72,9 @@ }, { "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))" @@ -100,24 +82,11 @@ }, { "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", - " | | | \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", - " | | | \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 \"\" 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", - " | | | , DataSet:\n", - " location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#016_test_missing_attr_15-44-09'\n", - " | | | ]\" not supported, storing as string\n", - "root - WARNING - Type \"\" for \"nested_dataset\":\"DataSet:\n", - " location = '/Users/unga/src/Qcodes/qcodes/unittest_data/2017-03-10/#016_test_missing_attr_15-44-09'\n", - " | | | \" not supported, storing as string\n", - "root - WARNING - List of mixed type for \"\":\"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", - " | | | \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", - " | | | \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": {}, diff --git a/docs/examples/Tutorial.ipynb b/docs/examples/Tutorial.ipynb index 6542ec0222d..05a9c039ad7 100644 --- a/docs/examples/Tutorial.ipynb +++ b/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, diff --git a/docs/examples/driver_examples/Qcodes example with Yokogawa.ipynb b/docs/examples/driver_examples/Qcodes example with Yokogawa GS2xx.ipynb similarity index 98% rename from docs/examples/driver_examples/Qcodes example with Yokogawa.ipynb rename to docs/examples/driver_examples/Qcodes example with Yokogawa GS2xx.ipynb index 5cea9affa7e..6b2e956cad5 100644 --- a/docs/examples/driver_examples/Qcodes example with Yokogawa.ipynb +++ b/docs/examples/driver_examples/Qcodes example with Yokogawa GS2xx.ipynb @@ -1,5 +1,12 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Qcodes example with Yokogawa GS200/GS210" + ] + }, { "cell_type": "code", "execution_count": 1, @@ -553,7 +560,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.6.2" + "version": "3.6.3" } }, "nbformat": 4, diff --git a/docs/examples/driver_examples/Qcodes example with AMI430.ipynb b/docs/examples/driver_examples/Qcodes_example_with_AMI430.ipynb similarity index 100% rename from docs/examples/driver_examples/Qcodes example with AMI430.ipynb rename to docs/examples/driver_examples/Qcodes_example_with_AMI430.ipynb diff --git a/docs/examples/driver_examples/Qcodes example with HP8753D.ipynb b/docs/examples/driver_examples/Qcodes_example_with_HP8753D.ipynb similarity index 100% rename from docs/examples/driver_examples/Qcodes example with HP8753D.ipynb rename to docs/examples/driver_examples/Qcodes_example_with_HP8753D.ipynb diff --git a/docs/examples/driver_examples/Qcodes example with Keysight Infiniium Oscilloscope.ipynb b/docs/examples/driver_examples/Qcodes_example_with_Keysight_Infiniium_Oscilloscope.ipynb similarity index 100% rename from docs/examples/driver_examples/Qcodes example with Keysight Infiniium Oscilloscope.ipynb rename to docs/examples/driver_examples/Qcodes_example_with_Keysight_Infiniium_Oscilloscope.ipynb diff --git a/qcodes/instrument/parameter.py b/qcodes/instrument/parameter.py index 2bc5880f161..664090f1a92 100644 --- a/qcodes/instrument/parameter.py +++ b/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.