add doc first example (notebook) using nbsphinx

doc/_templates/layout.html

@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+{%- block extrahead %}
+<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.22/require.min.js"></script>
+{%- for scriptfile in script_files %}
+      <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
+{%- endfor %}
+{% endblock %}

doc/conf.py

@@ -54,6 +54,7 @@
     # 'numpydoc',
     'IPython.sphinxext.ipython_directive',
     'IPython.sphinxext.ipython_console_highlighting',
+    'nbsphinx',
 ]
 
 extlinks = {
@@ -103,7 +104,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'

doc/environment.yml

@@ -1,4 +1,4 @@
-name: xarray-simlab
+name: xarray-simlab-doc
 channels:
   - conda-forge
   - defaults
@@ -7,4 +7,8 @@ dependencies:
   - numpy=1.12
   - xarray=0.9.6
   - ipython=6.1.0
+  - ipykernel=4.6.1
+  - nbconvert=5.2.1
   - sphinx=1.6.2
+  - nbsphinx=0.2.13
+  - pandoc=1.19.2

doc/examples.rst

@@ -0,0 +1,9 @@
+.. _examples:
+
+Examples
+========
+
+.. toctree::
+    :maxdepth: 2
+
+    examples/landscape-evolution-model

doc/index.rst

@@ -16,6 +16,7 @@ Documentation Index
 * :doc:`about`
 * :doc:`faq`
 * :doc:`installing`
+* :doc:`examples`
 
 .. toctree::
    :maxdepth: 1
@@ -25,6 +26,7 @@ Documentation Index
    about
    faq
    installing
+   examples
 
 **Help & reference**