more fixes for gallery

docs/source/.gitignore

@@ -0,0 +1 @@
+auto_examples/

docs/source/conf.py

@@ -17,6 +17,8 @@
 sys.path.insert(0, os.path.abspath('../../src/'))
 sys.path.insert(0, os.path.abspath('../../src/MicroStructPy/'))
 
+import sphinx_gallery
+
 
 # -- Project information -----------------------------------------------------
 
@@ -25,9 +27,9 @@
 author = 'Kenneth Hart'
 
 # The short X.Y version
-version = '3.0'
+version = '1.0'
 # The full version, including alpha/beta/rc tags
-release = '3.0'
+release = '1.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -43,7 +45,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'sphinx_gallery.gen_gallery',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -87,6 +90,11 @@
     'xmltodict']
 autodoc_member_order = 'groupwise'
 
+sphinx_gallery_conf = {
+    'examples_dirs': '../../sphinx_gallery',
+    'gallery_dirs': 'auto_examples',
+}
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -229,6 +237,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'MicroStructPy', 'MicroStructPy Documentation',
-     author, 'MicroStructPy', 'One line description of project.',
+     author, 'MicroStructPy',
+     'Microstructure modeling, mesh generation, analysis, and visualization.',
      'Miscellaneous'),
 ]

docs/source/index.rst

@@ -68,6 +68,7 @@ and the Python package.
 
    getting_started
    examples
+   auto_examples/index
    cli
    package_guide
    troubleshooting

sphinx_gallery/README.rst

@@ -0,0 +1,2 @@
+Gallery of Examples
+===================

sphinx_gallery/intro/README.rst

@@ -0,0 +1,5 @@
+Command Line Introduction
+-------------------------
+
+These examples introduce the options available in XML input files, excuted
+from the command line.

sphinx_gallery/intro/plot_intro_1.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+r"""
+1. Basic Example
+++++++++++++++++
+
+This input files contains two phases with a few options.
+
+XML Input File
+^^^^^^^^^^^^^^
+
+The basename for this file is ``intro_1_basic.xml``.
+The file can be run using this command::
+
+    microstructpy --demo=intro_1_basic.xml
+
+File contents:
+
+.. literalinclude:: ../../../../examples/intro_1_basic.xml
+    :language: xml
+
+Explanation
+^^^^^^^^^^^
+
+There are two materials, in a 2:1 ratio based on volume.
+The first is a matrix, which is represented with small circles.
+The second material consists of circular inclusions with diameter 2.
+These two materials fill a square domain.
+The bottom-left corner of the rectangle is the origin, which puts the
+rectangle in the first quadrant.
+The side length is 20, which is 10x the size of the inclusions.
+PNG files of each step in the process will be output, as well as the
+intermediate text files.
+They are saved in a folder named ``intro_1_basic``, in the current directory
+(i.e ``./intro_1_basic``).
+
+Output Plots
+^^^^^^^^^^^^
+
+"""
+
+# sphinx_gallery_thumbnail_number = 3
+
+import os
+import shutil
+
+import matplotlib.pyplot as plt
+import pylab
+
+import microstructpy as msp
+
+filename = '../../examples/intro_1_basic.xml'
+
+in_data = msp.cli.read_input(filename)
+phases = in_data['material']
+domain = in_data['domain']
+kwargs = in_data['settings']
+kwargs['verbose'] = False
+msp.cli.run(phases, domain, **kwargs)
+
+dpi = 300
+
+for plot_name in ['seeds', 'polymesh', 'trimesh']:
+    src = os.path.join('../../examples/intro_1_basic', plot_name + '.png')
+    im = plt.imread(src)
+
+    figsize = (im.shape[0] / dpi, im.shape[1] / dpi)
+
+    fig = plt.figure(figsize=figsize, dpi=dpi)
+    ax = fig.add_axes([0, 0, 1, 1])
+    ax.set_axis_off()
+    ax.get_xaxis().set_visible(False)
+    ax.get_yaxis().set_visible(False)
+    plt.imshow(im)
+    plt.axis('tight')

sphinx_gallery/plot_colors.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+r"""
+Colormaps alter your perception
+===============================
+
+Here I plot the function
+
+.. math:: f(x, y) = \sin(x) + \cos(y)
+
+with different colormaps.
+
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+x = np.linspace(-np.pi, np.pi, 300)
+xx, yy = np.meshgrid(x, x)
+z = np.cos(xx) + np.cos(yy)
+
+plt.figure()
+plt.imshow(z)
+
+plt.figure()
+plt.imshow(z, cmap=plt.cm.get_cmap('hot'))
+
+plt.figure()
+plt.imshow(z, cmap=plt.cm.get_cmap('Spectral'),
+           interpolation='none')
+
+# Not needed for the Gallery.
+# Only for direct execution
+plt.show()
+
+################################################
+# You can define blocks in your source code
+# with interleaving prose.
+#
+
+print("This writes to stdout and will be",
+      " displayed in the HTML file")

sphinx_gallery/plot_exp.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""
+Plotting the exponential function
+=================================
+A simple example for ploting two figures of a exponential
+function in order to test the autonomy of the gallery
+stacking multiple images.
+"""
+
+# Code source: Óscar Nájera
+# License: BSD 3 clause
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def main():
+    N = 100
+    x = np.linspace(-1, 2, N)
+    y = np.exp(x)
+
+    plt.figure()
+    plt.plot(x, y)
+    plt.xlabel('$x$')
+    plt.ylabel('$\exp(x)$')
+
+    plt.figure()
+    plt.plot(x, -np.exp(-x))
+    plt.xlabel('$x$')
+    plt.ylabel('$-\exp(-x)$')
+
+    plt.show()
+
+if __name__ == '__main__':
+    main()

src/microstructpy/cli.py

@@ -525,7 +525,8 @@ def run(phases, domain, verbose=False, restart=True, directory='.',
     # Perform Verification                                                    #
     # ----------------------------------------------------------------------- #
     if not verify:
-        print('Finished running MicroStructPy.')
+        if verbose:
+            print('Finished running MicroStructPy.')
         return
 
     if verbose:

tox.ini

@@ -36,23 +36,7 @@ commands = python setup.py sdist check --strict --metadata
 
 [testenv:docs]
 deps = sphinx
-       sphinx_rtd_theme
-basepython = python3.6
-skip_install = true
-commands = pip install pybind11
-           pip install -e .
-           microstructpy examples/*.xml
-           python examples/docs_banner.py
-           python examples/from_image.py
-           python examples/grain_neighborhoods.py
-           python examples/standard_voronoi.py
-           python examples/uniform_seeding.py
-           sphinx-apidoc -M -e -o docs/source/ src/microstructpy
-           sphinx-build docs/source/ docs/build/
-
-
-[testenv:docs-fast]
-deps = sphinx
+       sphinx-gallery
 basepython = python3.6
 commands = sphinx-apidoc -M -e -o docs/source/ src/microstructpy
            sphinx-build docs/source/ docs/build/