Merge pull request #165 from dsten/sam-tutorial

Tutorial

.gitignore

@@ -61,3 +61,4 @@ cache/
 
 docs/_build/
 docs/_autosummary/
+docs/normal_data.csv

.travis.yml

@@ -26,7 +26,7 @@ addons:
 before_install:
   - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
   - chmod +x miniconda.sh
-  - ./miniconda.sh -b -p $HOME/miniconda
+  - ./miniconda.sh -b -f -p $HOME/miniconda
   - export PATH=/home/travis/miniconda/bin:$PATH
   - conda update --yes conda
 
@@ -35,14 +35,18 @@ install:
   # TODO(sam): Add --upgrade flag when it works again
   - python3 setup.py install
 
+# https://docs.travis-ci.com/user/gui-and-headless-browsers/#Using-xvfb-to-Run-Tests-That-Require-a-GUI
+# sam: Not exactly sure why we need to initialize a display for this but it
+#      helps the tutorial plots build on Travis
+before_script:
+  - "export DISPLAY=:99.0"
+  - "sh -e /etc/init.d/xvfb start"
+  - sleep 3 # give xvfb some time to start
+
 script:
   - coverage run setup.py test
-  - cd docs && make html-raise-on-warning && cd ..
+  - make docs
 
 after_success:
   - coveralls
   - bash tools/deploy_docs.sh
-
-cache:
-  directories:
-  - /home/travis/virtualenv/python3.4.2/

docs/Makefile

@@ -52,11 +52,13 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 html:
+	mkdir -p $(BUILDDIR)/html/_images
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 html-raise-on-warning:
+	mkdir -p $(BUILDDIR)/html/_images
 	$(SPHINXBUILD) -W -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
 dirhtml:

docs/conf.py

@@ -35,6 +35,21 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
+    # These IPython extensions allow for embedded IPython code that gets rerun
+    # at build time.
+    'IPython.sphinxext.ipython_console_highlighting',
+    'IPython.sphinxext.ipython_directive'
+]
+
+# The following lines silence the matplotlib.use warnings since we import
+# matplotlib in each ipython directive block
+ipython_mplbackend = None
+ipython_execlines = [
+  'import matplotlib',
+  'matplotlib.use("Agg", warn=False)',
+  'import numpy as np',
+  'import matplotlib.pyplot as plt',
+  'plt.style.use("fivethirtyeight")',
 ]
 
 # Config autosummary
@@ -147,6 +162,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
+ipython_savefig_dir = './_build/html/_images'
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/sample.csv

@@ -0,0 +1,4 @@
+x,y,z
+1,10,100
+2,11,101
+3,12,102