Integrate tutorial notebooks into sphinx-docs build.

timstaley · Nov 21, 2016 · 10d7456 · 10d7456
1 parent 69d0a14
commit 10d7456
Show file tree

Hide file tree

Showing 9 changed files with 995 additions and 18 deletions.
diff --git a/documentation/requirements.txt b/documentation/requirements.txt
@@ -1,4 +1,4 @@
-lxml>=2.3
-sphinx>=1.3
-sphinx_rtd_theme #If building locally.
-
+sphinx>=1.4
+sphinx_rtd_theme
+jupyter
+nbsphinx
diff --git a/documentation/source/conf.py b/documentation/source/conf.py
@@ -1,4 +1,3 @@
-
 import sys, os
 import voeventparse
 
@@ -9,18 +8,20 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo',
-               'sphinx.ext.coverage', 'sphinx.ext.viewcode',
-               'sphinx.ext.napoleon']
-
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.intersphinx',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.napoleon',
+              'nbsphinx',
+              'IPython.sphinxext.ipython_console_highlighting',
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -35,7 +36,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -50,16 +51,14 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'VOEvent-parsedoc'
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
 
 # -- Custom options ----------------------
 autodoc_member_order = 'bysource'
 todo_include_todos = True
 
-nitpicky=True
+nitpicky = True
 nitpick_ignore = [
     ("py:obj", "lxml.etree.DocumentInvalid"),
     ("py:obj", "lxml.etree"),

diff --git a/documentation/source/examples.rst b/documentation/source/examples.rst
@@ -4,10 +4,9 @@ Usage examples
 ==============
 
 .. note::
-    See also the `tutorial notebooks`_, which give a step-by-step introduction
-    to using voevent-parse.
-
-.. _tutorial notebooks: https://github.com/timstaley/voevent-parse-tutorial
+    These scripts give some quick syntax examples.
+    See also the :ref:`tutorial` notebooks, for a step-by-step introduction
+    to using voevent-parse and working with XML data.
 
 
 Basic data access and manipulation

diff --git a/documentation/source/index.rst b/documentation/source/index.rst
@@ -18,6 +18,7 @@ Contents
 
     intro
     examples
+    tutorial/index
     reference
     changelog