Integrate tutorial notebooks in Sphinx documentation

.gitignore

@@ -53,6 +53,7 @@ distribute-*.tar.gz
 htmlcov
 MANIFEST
 
+# notebooks
 *.ipynb
 *.ipynb_checkpoints
 

.travis.yml

@@ -27,13 +27,13 @@ env:
         - NUMPY_VERSION=stable
         - ASTROPY_VERSION=stable
 
-        - CONDA_DEPENDENCIES='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils sherpa libgfortran regions reproject'
-        - CONDA_DEPENDENCIES_OSX='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils sherpa regions reproject'
-        - CONDA_DEPENDENCIES_WO_SHERPA='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils regions reproject'
-        - CONDA_DOCS_DEPENDENCIES='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils pygments aplpy sherpa libgfortran regions reproject'
-        - CONDA_DOCS_DEPENDENCIES_WO_SHERPA='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils pygments aplpy regions reproject'
-        - CONDA_DEPENDENCIES_NOTEBOOKS='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils aplpy sherpa libgfortran runipy regions reproject'
-        - CONDA_DEPENDENCIES_NOTEBOOKS_WO_SHERPA='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils aplpy libgfortran runipy regions reproject'
+        - CONDA_DEPENDENCIES='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils sherpa libgfortran regions reproject nbsphinx ipython'
+        - CONDA_DEPENDENCIES_OSX='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils sherpa regions reproject nbsphinx ipython'
+        - CONDA_DEPENDENCIES_WO_SHERPA='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils regions reproject nbsphinx ipython'
+        - CONDA_DOCS_DEPENDENCIES='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils pygments aplpy sherpa libgfortran regions reproject nbsphinx ipython'
+        - CONDA_DOCS_DEPENDENCIES_WO_SHERPA='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils pygments aplpy regions reproject nbsphinx ipython'
+        - CONDA_DEPENDENCIES_NOTEBOOKS='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils aplpy sherpa libgfortran runipy regions reproject nbsphinx ipython'
+        - CONDA_DEPENDENCIES_NOTEBOOKS_WO_SHERPA='Cython click scipy healpy h5py matplotlib pyyaml scikit-image scikit-learn pandas naima photutils aplpy libgfortran runipy regions reproject nbsphinx ipython'
 
         - PIP_DEPENDENCIES='uncertainties'
 

Makefile

@@ -48,7 +48,7 @@ help:
 	@echo ''
 
 clean:
-	rm -rf build dist docs/_build docs/api htmlcov MANIFEST gammapy.egg-info .coverage .cache
+	rm -rf build dist docs/_build docs/api docs/notebooks htmlcov MANIFEST gammapy.egg-info .coverage .cache
 	find . -name "*.pyc" -exec rm {} \;
 	find . -name "*.so" -exec rm {} \;
 	find gammapy -name '*.c' -exec rm {} \;

docs/conf.py

@@ -28,6 +28,7 @@
 import datetime
 import os
 import sys
+from distutils.dir_util import copy_tree
 
 try:
     import astropy_helpers
@@ -79,6 +80,16 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns.append('_templates')
+exclude_patterns.append('**.ipynb_checkpoints')
+
+
+#
+# -- nbsphinx settings
+extensions.append('nbsphinx')
+extensions.append('IPython.sphinxext.ipython_console_highlighting')
+extensions.append('sphinx.ext.mathjax')
+nbsphinx_execute = 'never'
+# --
 
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
@@ -178,6 +189,12 @@
 from gammapy.utils.docs import gammapy_sphinx_ext_activate
 gammapy_sphinx_ext_activate()
 
+# copy notebooks
+if os.environ['GAMMAPY_EXTRA']:
+    gammapy_extra_notebooks_folder = os.environ['GAMMAPY_EXTRA'] + '/notebooks'
+    if os.path.isdir(gammapy_extra_notebooks_folder):
+        copy_tree(gammapy_extra_notebooks_folder, 'notebooks')
+
 html_style = 'gammapy.css'
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -209,6 +226,7 @@
     edit_on_github_source_root = ""
     edit_on_github_doc_root = "docs"
 
+
 github_issues_url = 'https://github.com/gammapy/gammapy/issues/'
 
 # -- Other options --
@@ -217,6 +235,7 @@
 # show inherited members for classes
 automodsumm_inherited_members = True
 
+
 # In `about.rst` and `references.rst` we are giving lists of citations
 # (e.g. papers using Gammapy) that partly aren't referenced from anywhere
 # in the Gammapy docs. This is normal, but Sphinx emits a warning.

docs/environment.yml

@@ -18,3 +18,5 @@ dependencies:
   - aplpy
   - sphinx
   - pyyaml
+  - nbsphinx
+  - ipython

docs/image/sky_image.rst

@@ -18,7 +18,7 @@ Getting started
 
 Most easily a `~gammapy.image.SkyImage` can be created from a fits file:
 
-.. code::
+.. code:: python
 
     from gammapy.image import SkyImage
 
@@ -29,21 +29,21 @@ Alternatively an empty image can be created from the scratch, by specifying the
 WCS information (see `~gammapy.image.SkyImage.empty` for a detailed description of
 the parameters):
 
-.. code::
+.. code:: python
 
     image_empty = SkyImage.empty('empty')
 
 Where the optional string ``'empty'`` specifies the name of the image.
 
 Some basic info on the image is shown when calling:
 
-.. code::
+.. code:: python
 
     image.info()
 
 To lookup the value of the data at a certain sky position one can do:
 
-.. code::
+.. code:: python
 
     from astropy.coordinates import SkyCoord
     position = SkyCoord(0, 0, frame='galactic', unit='deg')
@@ -132,4 +132,4 @@ of computing large model sky images:
         cutout.data = source(l.deg, b.deg)
         image.paste(cutout)
 
-    image.show()
+    image.show()

docs/index.rst

@@ -46,14 +46,23 @@ General documentation
   development/index
   changelog
 
+.. _gammapy_notebooks:
+
+IPython notebooks
+---------------------
+.. toctree::
+  :maxdepth: 1
+
+  notebooks
+
 .. _gammapy_toolbox:
 
 The Gammapy toolbox
 -------------------
 
 .. toctree::
   :maxdepth: 1
- 
+
   scripts/index
   astro/index
   background/index

docs/maps/hpxmap.rst

@@ -19,7 +19,7 @@ of non-spatial axes (e.g. energy).  By default a HEALPix geometry will
 encompass the full sky.  The following example shows how to create
 an all-sky 2D HEALPix image:
 
-.. code::
+.. code:: python
 
    from gammapy.maps import HpxGeom
    # Create a HEALPix geometry of NSIDE=16
@@ -33,7 +33,7 @@ Partial-sky maps can be created by passing a ``region`` argument to
 the map geometry constructor or by setting the ``width`` argument to
 the `~gammapy.maps.HpxMap.create` factory method:
 
-.. code::
+.. code:: python
 
    from gammapy.maps import HpxGeom, HpxMap, HpxMapND
    from astropy.coordinates import SkyCoord
@@ -42,13 +42,13 @@ the `~gammapy.maps.HpxMap.create` factory method:
    geom = HpxGeom(16, region='DISK(0.0,5.0,10.0)', coordsys='GAL')
    m = HpxMapND(geom)
 
-   # Equivalent factory method call  
+   # Equivalent factory method call
    position = SkyCoord(0.0, 5.0, frame='galactic', unit='deg')
    m = HpxMap.create(nside=16, skydir=position, width=20.0)
 
 
 
-   
+
 
 Sparse Maps
 -----------