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 ipython/ipython#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 e8367b9. * add title * Better name * make sure that autogen api is removed too
microsoft · Dec 6, 2017 · b9ab98d · b9ab98d
1 parent 9f16ffa
commit b9ab98d
Show file tree

Hide file tree

Showing 10 changed files with 60 additions and 153 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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": {},

diff --git 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/...amples/Qcodes example with Yokogawa.ipynb → .../Qcodes example with Yokogawa GS2xx.ipynb b/...amples/Qcodes example with Yokogawa.ipynb → .../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/...examples/Qcodes example with AMI430.ipynb → ...examples/Qcodes_example_with_AMI430.ipynb b/...examples/Qcodes example with AMI430.ipynb → ...examples/Qcodes_example_with_AMI430.ipynb
diff --git a/...xamples/Qcodes example with HP8753D.ipynb → ...xamples/Qcodes_example_with_HP8753D.ipynb b/...xamples/Qcodes example with HP8753D.ipynb → ...xamples/Qcodes_example_with_HP8753D.ipynb
diff --git a/...ith Keysight Infiniium Oscilloscope.ipynb → ...ith_Keysight_Infiniium_Oscilloscope.ipynb b/...ith Keysight Infiniium Oscilloscope.ipynb → ...ith_Keysight_Infiniium_Oscilloscope.ipynb