Merge pull request #574 from reneeotten/examples

Gallery with examples

.gitignore

@@ -2,6 +2,8 @@
 *~
 *#
 doc/_build
+doc/examples
+examples/documentation
 doc/*.pdf
 doc/extensions.py
 build

.travis.yml

@@ -29,7 +29,7 @@ install:
     - if [[ $version == minimum && $TRAVIS_PYTHON_VERSION == 3.6 ]]; then conda create -q -n test_env python=$TRAVIS_PYTHON_VERSION numpy=1.11.2 scipy=0.19 six=1.10; fi
     - if [[ $version == minimum && $TRAVIS_PYTHON_VERSION == 3.7-dev ]]; then conda create -q -n test_env python=3.7 numpy=1.11.3 scipy=1.1 six=1.11; fi
     - if [[ $version == latest && $TRAVIS_PYTHON_VERSION != 3.7-dev ]]; then conda create -q -n test_env python=$TRAVIS_PYTHON_VERSION numpy scipy six pandas matplotlib dill; fi
-    - if [[ $version == latest && $TRAVIS_PYTHON_VERSION == 3.7-dev ]]; then conda create -q -n test_env python=3.7 numpy scipy six pandas matplotlib dill sphinx jupyter_sphinx corner; fi
+    - if [[ $version == latest && $TRAVIS_PYTHON_VERSION == 3.7-dev ]]; then conda create -q -n test_env python=3.7 numpy scipy six pandas matplotlib dill sphinx jupyter_sphinx corner sphinx-gallery; fi
     - source activate test_env
     - pip install pytest
     - pip install codecov

doc/Makefile

@@ -19,32 +19,37 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 html:
 	cp sphinx/ext_mathjax.py extensions.py
-	cp ../examples/*.dat .
+	./doc_examples_to_gallery.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	cp -r examples $(BUILDDIR)/html
 	@echo
 	@echo "html build finished: $(BUILDDIR)/html."
-	rm -f *.dat *.sav
+	rm -f *.dat *.sav *.csv
+	rm -rf ../examples/documentation
 
 htmlzip: html
 	cp sphinx/ext_mathjax.py extensions.py
-	cp ../examples/*.dat .
+	./doc_examples_to_gallery.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/lmfit_doc
+	cp -r examples $(BUILDDIR)/html
 	cd $(BUILDDIR) && zip -pur html/lmfit_doc.zip lmfit_doc
-	rm -f *.dat *.sav
+	rm -f *.dat *.sav *.csv
+	rm -rf ../examples/documentation
 
 epub:
 	cp sphinx/ext_mathjax.py extensions.py
-	cp ../examples/*.dat .
+	./doc_examples_to_gallery.py
 	$(SPHINXBUILD) -b epub  $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	cp -pr $(BUILDDIR)/epub/*.epub $(BUILDDIR)/html/.
-	rm -f *.dat *.sav
+	rm -f *.dat *.sav *.csv
+	rm -rf ../examples/documentation
 
 pdf: latex
 	cp sphinx/ext_imgmath.py extensions.py
 	cp ../examples/*.dat .
 	cd $(BUILDDIR)/latex && make all-pdf
 	cp -pr $(BUILDDIR)/latex/lmfit.pdf $(BUILDDIR)/html/.
-	rm -f *.dat *.sav
+	rm -f *.dat *.sav *.csv
 
 all: html htmlzip epub pdf
 
@@ -70,7 +75,9 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 	-rm -f extensions.py
-	-rm -f *.dat *.sav
+	-rm -f *.dat *.sav *.csv
+	-rm -rf examples
+	-rm -rf ../examples/documentation
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -101,7 +108,7 @@ latex:
 	@echo "Build finished; the LaTeX files are in _build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
-	rm -f *.dat *.sav
+	rm -f *.dat *.sav *.csv
 
 latexpdf:
 	cp sphinx/ext_imgmath.py extensions.py
@@ -110,7 +117,7 @@ latexpdf:
 	@echo "Running LaTeX files through pdflatex..."
 	make -C _build/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in _build/latex."
-	rm -f *.dat *.sav
+	rm -f *.dat *.sav *.csv
 
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

doc/conf.py

@@ -159,3 +159,12 @@
 os.environ['PYTHONPATH'] = ':'.join((package_path, os.environ.get('PYTHONPATH', '')))
 
 image_converter_args=["-density", "300"]
+
+# Sphinx-gallery configuration
+sphinx_gallery_conf = {
+    'examples_dirs': '../examples',
+    'gallery_dirs': 'examples',
+    'filename_pattern': '/documentation|/example_',
+    'ignore_pattern': '/doc_',
+    'expected_failing_examples': ['../examples/documentation/model_loadmodel.py']
+}

doc/doc_examples_to_gallery.py

@@ -0,0 +1,53 @@
+#! /usr/bin/env python
+
+"""
+Process the examples in the documentation for inclusion in the Gallery:
+
+- create a "documentation" directory within "examples"
+- add a README.txt file
+- copy the examples from the documentation, bu remove the "doc_" from the
+   filename
+- add the required docstring to the files for proper rendering
+- copy the data files
+
+"""
+import os
+
+basedir = os.getcwd()
+
+examples_dir = os.path.join(os.getcwd(), '../examples')
+files = [fn for fn in os.listdir(examples_dir) if fn.startswith('doc_')]
+
+examples_documentation_dir = os.path.join(examples_dir, 'documentation')
+os.makedirs(examples_documentation_dir, exist_ok=True)
+
+with open(os.path.join(examples_documentation_dir, 'README.txt'), 'w') as out:
+    out.write("Examples from the documentation\n")
+    out.write("===============================\n\n")
+    out.write("Below are all the examples that are part of the lmfit documentation.")
+
+for fn in files:
+    gallery_file = os.path.join(examples_documentation_dir, fn[4:])
+    with open(gallery_file, 'w') as out:
+        if fn == 'doc_model_loadmodel.py':
+            msg = ('This example *does* actually work, but for some reason the '
+                   'conversion using sphinx-gallery fails....')
+            out.write('"""\n{}\n{}\n\n{}\n\n"""\n'.format(fn, "="*len(fn), msg))
+        else:
+            out.write('"""\n{}\n{}\n\n"""\n'.format(fn, "="*len(fn)))
+    os.system('cat {} >> {}'.format(os.path.join(examples_dir, fn), gallery_file))
+
+    # make sure the saved Models and ModelResult are available
+    if 'save' in fn:
+        os.chdir(examples_dir)
+        os.system('python {}'.format(fn))
+        os.chdir(basedir)
+
+os.system('cp {}/*.dat {}'.format(examples_dir, examples_documentation_dir))
+os.system('cp {}/*.csv {}'.format(examples_dir, examples_documentation_dir))
+os.system('cp {}/*.sav {}'.format(examples_dir, examples_documentation_dir))
+
+# data files for the other Gallery examples
+os.system('cp {}/*.dat .'.format(examples_dir))
+os.system('cp {}/*.csv .'.format(examples_dir))
+os.system('cp {}/*.sav .'.format(examples_dir))

doc/sphinx/ext_mathjax.py

@@ -7,4 +7,5 @@
               'sphinx.ext.napoleon',
               'sphinx.ext.todo',
               'IPython.sphinxext.ipython_console_highlighting',
-              'jupyter_sphinx.execute']
+              'jupyter_sphinx.execute',
+              'sphinx_gallery.gen_gallery']

doc/sphinx/theme/lmfitdoc/layout.html

@@ -27,14 +27,15 @@
    <li><a href="{{ pathto('builtin_models') }}"> built-in models</a>|</li>
    <li><a href="{{ pathto('confidence') }}">confidence intervals</a>|</li>
    <li><a href="{{ pathto('bounds') }}">bounds</a>|</li>
-   <li><a href="{{ pathto('constraints') }}">constraints</a>]</li>
+   <li><a href="{{ pathto('constraints') }}">constraints</a>|</li>
+   <li><a href="{{ pathto('examples/index') }}">examples</a>]</li>
 {% endblock %}
 
 {% block relbar1 %}
 <div>
 <table border=0>
   <tr><td></td><td width=85% padding=5 align=left>
-       <a href="index.html" style="color: #157"> <font size=+3>LMFIT</font></a>
+          <a href="{{ pathto('index') }}" style="color: #157"> <font size=+3>LMFIT</font></a>
      </td>
      <td width=7% align=left>
          <a href="contents.html" style="color: #882222">