diff --git a/.gitignore b/.gitignore
index a2313843..c6acf4af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -73,3 +73,5 @@ Untitled.ipynb
 .mr.developer.cfg
 .project
 .pydevproject
+gallery/
+modules/
diff --git a/abipy/examples/plot/__init__.py b/abipy/examples/plot/__init__.py
index e69de29b..b992cedd 100644
--- a/abipy/examples/plot/__init__.py
+++ b/abipy/examples/plot/__init__.py
@@ -0,0 +1,7 @@
+r"""
+AbiPy examples
+==============
+
+There are a variety of ways to use AbiPy, and most of them are
+illustrated in the examples in this directory.
+"""
diff --git a/abipy/examples/plot/plot_bz.py b/abipy/examples/plot/plot_bz.py
index 386459ab..9cddde69 100755
--- a/abipy/examples/plot/plot_bz.py
+++ b/abipy/examples/plot/plot_bz.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Brillouin zone
+==============
+
 This example shows how to display the Brillouin zone
 with pymatgen and matplotlib.
 """
diff --git a/abipy/examples/plot/plot_den.py b/abipy/examples/plot/plot_den.py
index 836da339..d34c61ff 100755
--- a/abipy/examples/plot/plot_den.py
+++ b/abipy/examples/plot/plot_den.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Density
+=======
+
 This example shows how to analyze the electronic density
 stored in the DEN.nc file.
 """
diff --git a/abipy/examples/plot/plot_dfpt_cycle.py b/abipy/examples/plot/plot_dfpt_cycle.py
index 68c726f3..5e221fa4 100755
--- a/abipy/examples/plot/plot_dfpt_cycle.py
+++ b/abipy/examples/plot/plot_dfpt_cycle.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+DFPT SCF cycle
+==============
+
 This example shows how to plot the results of the DFPT
 self-consistent cycle reported in the main output file.
 """
diff --git a/abipy/examples/plot/plot_ebands.py b/abipy/examples/plot/plot_ebands.py
index 61fdbcd2..d035aefd 100755
--- a/abipy/examples/plot/plot_ebands.py
+++ b/abipy/examples/plot/plot_ebands.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Band structure plot
+===================
+
 This example shows how to plot a band structure
 using the eigenvalues stored in the GSR file 
 produced at the end of the GS run.
diff --git a/abipy/examples/plot/plot_ebands_boxplot.py b/abipy/examples/plot/plot_ebands_boxplot.py
index e4399c95..813ee3a0 100755
--- a/abipy/examples/plot/plot_ebands_boxplot.py
+++ b/abipy/examples/plot/plot_ebands_boxplot.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Seaborn boxplot
+===============
+
 This example shows how to use seaborn to draw a box plot 
 showing the distributions of eigenvalues with respect to the band index.
 """
diff --git a/abipy/examples/plot/plot_ebands_edos.py b/abipy/examples/plot/plot_ebands_edos.py
index 69c16e64..8bfd2569 100755
--- a/abipy/examples/plot/plot_ebands_edos.py
+++ b/abipy/examples/plot/plot_ebands_edos.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Bands + DOS
+===========
+
 This example shows how to compute the DOS and plot a
 band structure with DOS using two GSR files.
 """
diff --git a/abipy/examples/plot/plot_ebands_grid.py b/abipy/examples/plot/plot_ebands_grid.py
index b17d99b7..6b6bb03b 100755
--- a/abipy/examples/plot/plot_ebands_grid.py
+++ b/abipy/examples/plot/plot_ebands_grid.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+ElectronBandsPlotter
+====================
+
 This example shows how to plot several band structures on a grid
 
 We use two GSR files:
@@ -28,6 +31,7 @@ plotter.gridplot()
 eb_objects = 2 * [ref_file("si_nscf_GSR.nc")]
 edos_objects = 2 * [ref_file("si_scf_GSR.nc")]
 
+# sphinx_gallery_thumbnail_number = 2
 plotter = ElectronBandsPlotter()
 plotter.add_ebands("Si", ref_file("si_nscf_GSR.nc"), dos=ref_file("si_scf_GSR.nc"))
 plotter.add_ebands("Same data", ref_file("si_nscf_GSR.nc"), dos=ref_file("si_scf_GSR.nc"))
diff --git a/abipy/examples/plot/plot_ebands_scatter3d.py b/abipy/examples/plot/plot_ebands_scatter3d.py
index 0bf19cb0..fc512e72 100755
--- a/abipy/examples/plot/plot_ebands_scatter3d.py
+++ b/abipy/examples/plot/plot_ebands_scatter3d.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+e-bands scatter3d
+=================
+
 This example shows how to plot a particular "band" in 3D 
 with matplotlib scatter3D.
 The color of the point gives the energy of the state wrt to the Fermi level.
diff --git a/abipy/examples/plot/plot_ebands_spin.py b/abipy/examples/plot/plot_ebands_spin.py
index 6e2cd0b2..92f91ffb 100755
--- a/abipy/examples/plot/plot_ebands_spin.py
+++ b/abipy/examples/plot/plot_ebands_spin.py
@@ -1,6 +1,9 @@
 #!/usr/bin/env python
-"""
-This example shows how to plot the band structure of Nickel
+r"""
+Spin-polarized e-bands
+======================
+
+This example shows how to plot the band structure of nickel
 using the eigenvalues stored in the GSR file produced at the end of the GS run.
 """
 from abipy import abilab
diff --git a/abipy/examples/plot/plot_ederivatives.py b/abipy/examples/plot/plot_ederivatives.py
index 672b9f6a..0187efed 100755
--- a/abipy/examples/plot/plot_ederivatives.py
+++ b/abipy/examples/plot/plot_ederivatives.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Effective masses
+================
+
 This example shows how to compute and plot the derivatives of the
 KS eigenvalues along a high symmetry path in K-space.
 """
diff --git a/abipy/examples/plot/plot_edos.py b/abipy/examples/plot/plot_edos.py
index b3d62922..d19d7b5d 100755
--- a/abipy/examples/plot/plot_edos.py
+++ b/abipy/examples/plot/plot_edos.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Electron DOS
+============
+
 This example shows how to compute the DOS from
 the eigenvalues stored in the WFK file with the gaussian method.
 """
diff --git a/abipy/examples/plot/plot_edos_vs_broad.py b/abipy/examples/plot/plot_edos_vs_broad.py
index 56ed657c..863b4a9e 100755
--- a/abipy/examples/plot/plot_edos_vs_broad.py
+++ b/abipy/examples/plot/plot_edos_vs_broad.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Multiple e-DOSes
+================
+
 This example shows how to compute and plot multiple
 electron DOSes obtained with different values of the gaussian broadening.
 """
diff --git a/abipy/examples/plot/plot_efatbands.py b/abipy/examples/plot/plot_efatbands.py
index 11cd5515..8810a197 100755
--- a/abipy/examples/plot/plot_efatbands.py
+++ b/abipy/examples/plot/plot_efatbands.py
@@ -1,6 +1,9 @@
 #!/usr/bin/env python
-"""
-This example shows how to plot the L-projected fatbands of MgB2 
+r"""
+MgB2 fatbands
+=============
+
+This example shows how to plot the L-projected fatbands of MgB2
 using the FATBANDS.nc files produced by abinit with prtdos 3.
 See also PhysRevLett.86.4656
 """
@@ -45,6 +48,7 @@ fbnc_kmesh.plot_pjdos_lview(lmax=lmax, tight_layout=True)
 
 # Now we use the two netcdf files to produce plots with fatbands + PJDOSEs.
 # The data for the DOS is taken from pjdosfile.
+# sphinx_gallery_thumbnail_number = 6
 fbnc_kpath.plot_fatbands_with_pjdos(pjdosfile=fbnc_kmesh, lmax=lmax,
                                     view="type", tight_layout=True)
 
diff --git a/abipy/examples/plot/plot_efatbands_lm.py b/abipy/examples/plot/plot_efatbands_lm.py
index 94caada8..f8f372bf 100755
--- a/abipy/examples/plot/plot_efatbands_lm.py
+++ b/abipy/examples/plot/plot_efatbands_lm.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+LM-fatbands
+===========
+
 This example shows how to plot the LM-projected fatbands.
 The FATBANDS file must have benn produced with prtdos 3 and prtdosm 1.
 """
diff --git a/abipy/examples/plot/plot_efatbands_spin.py b/abipy/examples/plot/plot_efatbands_spin.py
index 4395de7b..9650039f 100755
--- a/abipy/examples/plot/plot_efatbands_spin.py
+++ b/abipy/examples/plot/plot_efatbands_spin.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+spin-polarized fatbands
+=======================
+
 This example shows how to plot the L-projected fatbands of Ni
 using the results stored in the FATBANDS.nc files produced with prtdos 3.
 """
diff --git a/abipy/examples/plot/plot_ejdos.py b/abipy/examples/plot/plot_ejdos.py
index b86ab7dc..a9922c29 100755
--- a/abipy/examples/plot/plot_ejdos.py
+++ b/abipy/examples/plot/plot_ejdos.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Joint Density of States
+=======================
+
 This example shows how plot the different contributions
 to the electronic joint density of states of Silicon
 """
diff --git a/abipy/examples/plot/plot_fermisurface.py b/abipy/examples/plot/plot_fermisurface.py
index dde2bdb0..fb687ab3 100755
--- a/abipy/examples/plot/plot_fermisurface.py
+++ b/abipy/examples/plot/plot_fermisurface.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+MgB2 Fermi surface
+==================
+
 This example shows how to plot the Fermi surface with matplotlib
 """
 from abipy.abilab import abiopen
diff --git a/abipy/examples/plot/plot_fold2bloch.py b/abipy/examples/plot/plot_fold2bloch.py
index 082860e9..6b835468 100755
--- a/abipy/examples/plot/plot_fold2bloch.py
+++ b/abipy/examples/plot/plot_fold2bloch.py
@@ -1,7 +1,10 @@
 #!/usr/bin/env python
-"""
+r"""
+Unfolding with fold2bloch
+=========================
+
 This example shows how to plot the results produced by fold2bloch.
-http://www.abinit.org/doc/helpfiles/for-v8.0/tutorial/lesson_fold2Bloch.html
+<http://www.abinit.org/doc/helpfiles/for-v8.0/tutorial/lesson_fold2Bloch.html>
 """
 from __future__ import division, print_function
 
@@ -10,11 +13,12 @@ import abipy.data as abidata
 import numpy as np
 
 with abilab.abiopen(abidata.ref_file("h6_FOLD2BLOCH.nc")) as ncfile:
-    #print(ncfile)
+    print(ncfile)
     # Plot folded bands
     ncfile.ebands.plot(title="Folded bands")
 
     # Plot unfolded bands along the path defined by kbounds.
     kbounds = [0, 1/2, 0, 0, 0, 0, 0, 0, 1/2]
-    klabels = ["Y", "$\Gamma$", "X"]
+    klabels = ["Y", r"$\Gamma$", "X"]
+    # sphinx_gallery_thumbnail_number = 2
     ncfile.plot_unfolded(kbounds, klabels, title="Unfolded bands")
diff --git a/abipy/examples/plot/plot_funcs.py b/abipy/examples/plot/plot_funcs.py
index 69852e74..9d8a62a2 100755
--- a/abipy/examples/plot/plot_funcs.py
+++ b/abipy/examples/plot/plot_funcs.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Function1D object
+=================
+
 This example shows how to use the Function1D object to analyze and plot results.
 """
 import numpy as np
diff --git a/abipy/examples/plot/plot_gruneisen.py b/abipy/examples/plot/plot_gruneisen.py
index b5dfdbba..f6ee9b8b 100755
--- a/abipy/examples/plot/plot_gruneisen.py
+++ b/abipy/examples/plot/plot_gruneisen.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Gruneisen parameters
+====================
+
 This example shows how to analyze the Gruneisen parameters
 computed by anaddb via finite difference. See also v8/Input/t45.in
 """
@@ -17,6 +20,7 @@ ncfile = abilab.abiopen(abidata.ref_file("mg2si_GRUNS.nc"))
 ncfile.plot_doses(title="DOSes available in the GRUNS file.")
 
 # Plot phonon bands with markers
+# sphinx_gallery_thumbnail_number = 2
 ncfile.plot_phbands_with_gruns(title="Phonon bands with markers proportional to Gruneisen parameters + DOSes")
 
 # Construct plotter object to analyze multiple phonon bands.
diff --git a/abipy/examples/plot/plot_gscycle.py b/abipy/examples/plot/plot_gscycle.py
index 51497e45..be257ecb 100755
--- a/abipy/examples/plot/plot_gscycle.py
+++ b/abipy/examples/plot/plot_gscycle.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Ground-state SCF cycle
+======================
+
 This example shows how to plot the results of the
 GS self-consistent cycle reported in the main output file.
 """
diff --git a/abipy/examples/plot/plot_hist.py b/abipy/examples/plot/plot_hist.py
index 8136acc9..46060702 100755
--- a/abipy/examples/plot/plot_hist.py
+++ b/abipy/examples/plot/plot_hist.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Structural relaxation
+=====================
+
 This example shows how to analyze the results of a 
 structure relaxation run using the HIST.nc file.
 """
diff --git a/abipy/examples/plot/plot_mdf.py b/abipy/examples/plot/plot_mdf.py
index c99c63a4..38190355 100755
--- a/abipy/examples/plot/plot_mdf.py
+++ b/abipy/examples/plot/plot_mdf.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Bethe-Salpeter
+==============
+
 This example shows how to plot the macroscopic dielectric function (MDF)
 computed in the Bethe-Salpeter code.
 """
diff --git a/abipy/examples/plot/plot_multiple_mdf.py b/abipy/examples/plot/plot_multiple_mdf.py
index ddeaae50..71423161 100755
--- a/abipy/examples/plot/plot_multiple_mdf.py
+++ b/abipy/examples/plot/plot_multiple_mdf.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Multiple Bethe-Salpeter calculations
+====================================
+
 This example shows how to analyze multiple MDF files.
 """
 import abipy.data as abidata
diff --git a/abipy/examples/plot/plot_optic.py b/abipy/examples/plot/plot_optic.py
index fb2e3a9a..b549e6df 100755
--- a/abipy/examples/plot/plot_optic.py
+++ b/abipy/examples/plot/plot_optic.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Optic results
+=============
+
 This example shows how to plot the optical properties
 computed by optic within the independent-particle approximation,
 no local-field effects and no excitonic effects.
@@ -35,6 +38,7 @@ filenames = [
 
 robot = abilab.OpticRobot.from_files(filenames)
 
+# sphinx_gallery_thumbnail_number = 3
 robot.plot_linopt_convergence(title="Convergence of $\epsilon$ wrt nkpt")
 
 robot.plot_shg_convergence(title="Convergence of $\chi^2(-2\omega,\omega,\omega)$ wrt nkpt")
diff --git a/abipy/examples/plot/plot_phbands_and_dos.py b/abipy/examples/plot/plot_phbands_and_dos.py
index 7446b4c8..c38388a9 100755
--- a/abipy/examples/plot/plot_phbands_and_dos.py
+++ b/abipy/examples/plot/plot_phbands_and_dos.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Phonon Band structures
+======================
+
 This example shows how to plot the phonon band structure of AlAs.
 See tutorial/lesson_rf2.html
 """
diff --git a/abipy/examples/plot/plot_phbands_grid.py b/abipy/examples/plot/plot_phbands_grid.py
index a212e688..4c380f5e 100755
--- a/abipy/examples/plot/plot_phbands_grid.py
+++ b/abipy/examples/plot/plot_phbands_grid.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Multiple phonon bands
+=====================
+
 This example shows how to plot several phonon band structures on a grid.
 
 We use two files produced by anaddb:
diff --git a/abipy/examples/plot/plot_phonon_fatbands.py b/abipy/examples/plot/plot_phonon_fatbands.py
index ad39fa58..829d90b8 100755
--- a/abipy/examples/plot/plot_phonon_fatbands.py
+++ b/abipy/examples/plot/plot_phonon_fatbands.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Phonon fatbands
+===============
+
 This example shows how to plot the phonon fatbands of AlAs.
 See tutorial/lesson_rf2.html
 """
@@ -10,20 +13,10 @@ import abipy.data as abidata
 with abiopen(abidata.ref_file("trf2_5.out_PHBST.nc")) as ncfile:
     phbands = ncfile.phbands
 
-# Mapping reduced coordinates -> labels (optional)
-#qlabels = {
-#    (0,0,0): "$\Gamma$",
-#    (0.375, 0.375, 0.75): "K",
-#    (0.5, 0.5, 1.0): "X",
-#    (0.5, 0.5, 0.5): "L",
-#    (0.5, 0.0, 0.5): "X",
-#    (0.5, 0.25, 0.75): "W",
-#}
-
 # Plot the phonon band structure.
 phbands.plot_fatbands(title="AlAs phonon fatbands without LO-TO splitting") #, qlabels=qlabels)
 
 # Plot the phonon band structure + PJDOS
+# sphinx_gallery_thumbnail_number = 2
 phdos_path = abidata.ref_file("trf2_5.out_PHDOS.nc")
-phbands.plot_fatbands(units="Thz", phdos_file=phdos_path,
-                      title="AlAs phonon fatbands with PJDOS")
+phbands.plot_fatbands(units="Thz", phdos_file=phdos_path, title="AlAs phonon fatbands with PJDOS")
diff --git a/abipy/examples/plot/plot_phonon_pjdos.py b/abipy/examples/plot/plot_phonon_pjdos.py
index 16e51ef4..7827f660 100755
--- a/abipy/examples/plot/plot_phonon_pjdos.py
+++ b/abipy/examples/plot/plot_phonon_pjdos.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Projected phonon DOS
+====================
+
 This example shows how to plot the projected phonon DOS of AlAs.
 See tutorial/lesson_rf2.html
 """
diff --git a/abipy/examples/plot/plot_phonons.py b/abipy/examples/plot/plot_phonons.py
index c2a70ed8..6b14e2db 100755
--- a/abipy/examples/plot/plot_phonons.py
+++ b/abipy/examples/plot/plot_phonons.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+AlAs Phonon bands
+=================
+
 This example shows how to plot the phonon band structure of AlAs.
 See tutorial/lesson_rf2.html
 """
diff --git a/abipy/examples/plot/plot_phonons_lo_to.py b/abipy/examples/plot/plot_phonons_lo_to.py
index f0d2394e..e2d55626 100755
--- a/abipy/examples/plot/plot_phonons_lo_to.py
+++ b/abipy/examples/plot/plot_phonons_lo_to.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Phonon Bands with LO-TO
+=======================
+
 This example shows how to plot the phonon band structure of AlAs 
 including the LO-TO splitting. See tutorial/lesson_rf2.html
 """
diff --git a/abipy/examples/plot/plot_phthermo.py b/abipy/examples/plot/plot_phthermo.py
index 300f6c8c..87b17c46 100755
--- a/abipy/examples/plot/plot_phthermo.py
+++ b/abipy/examples/plot/plot_phthermo.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Thermodinamic properties
+========================
+
 This example shows how to compute and plot thermodinamic properties within
 the harmonic approximation using the phonon DOS produced by anaddb.
 """
diff --git a/abipy/examples/plot/plot_potentials.py b/abipy/examples/plot/plot_potentials.py
index 7491779b..28a052fa 100755
--- a/abipy/examples/plot/plot_potentials.py
+++ b/abipy/examples/plot/plot_potentials.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Potentials
+==========
+
 This example shows how to plot the potentials stored in netcdf files.
 Use the input variables `prtpot`, `prtvha`, `prtvhxc`, `prtvxc` with
 `iomode 3` to produce these files at the end of the SCF-GS run.
diff --git a/abipy/examples/plot/plot_qpbands_with_interpolation.py b/abipy/examples/plot/plot_qpbands_with_interpolation.py
index ba6bc642..5c378d03 100755
--- a/abipy/examples/plot/plot_qpbands_with_interpolation.py
+++ b/abipy/examples/plot/plot_qpbands_with_interpolation.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
 """
+GW corrections
+==============
+
 This example shows how to interpolate the GW corrections and use the interpolated
 values to correct the KS band structure computed on a high symmetry k-path and
 the KS energies of a k-mesh. Finally, the KS and the GW results are plotted with matplotlib.
@@ -21,7 +24,7 @@ with abiopen(abidata.ref_file("si_scf_GSR.nc")) as gsr_scf:
 
 ks_edos = ks_ebands_kmesh.get_edos()
 
-# Interpolate the QP corrections and use the interpolated values to correct 
+# Interpolate the QP corrections and use the interpolated values to correct
 # the KS energies stored in `ks_ebands_kpath` and `ks_ebands_kmesh`.
 #
 # The QP energies are returned in r.qp_ebands_kpath and r.qp_ebands_kmesh.
@@ -55,6 +58,7 @@ plotter.add_ebands("GW (interpolated)", r.qp_ebands_kpath, dos=qp_edos)
 plotter.combiplot(title="Combiplot")
 plotter.boxplot(swarm=True, title="Boxplot")
 plotter.combiboxplot(swarm=True, title="Combiboxplot")
+# sphinx_gallery_thumbnail_number = 6
 plotter.gridplot(title="Gridplot")
 
 sigres.close()
diff --git a/abipy/examples/plot/plot_qpbands_with_scissor.py b/abipy/examples/plot/plot_qpbands_with_scissor.py
index dc12c88f..0a69852f 100755
--- a/abipy/examples/plot/plot_qpbands_with_scissor.py
+++ b/abipy/examples/plot/plot_qpbands_with_scissor.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+GW with scissors operator
+=========================
+
 This example shows how to generate an energy-dependent scissors operator
 by fitting the GW QPState corrections as function of the KS eigenvalues
 We then use the scissors operator to correct the KS band structure
diff --git a/abipy/examples/plot/plot_qpconverge.py b/abipy/examples/plot/plot_qpconverge.py
index 4c175135..88674eba 100755
--- a/abipy/examples/plot/plot_qpconverge.py
+++ b/abipy/examples/plot/plot_qpconverge.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+GW Convergence
+==============
+
 This example shows how to visualize the convergence of the
 QP results stored in the SIGRES produced by the GW code (sigma run).
 """
@@ -23,7 +26,7 @@ plotter.add_files(filepaths)
 plotter.plot_qpgaps(title="QP gaps vs sigma_nband", hspan=0.05)
 
 # Plot the convergence of the QP energies.
-plotter.plot_qpenes(spin=0, kpoint=[0, 0, 0], 
-                    title="QP energies vs sigma_nband", hspan=0.05)
+plotter.plot_qpenes(spin=0, kpoint=[0, 0, 0], title="QP energies vs sigma_nband", hspan=0.05)
 
+# sphinx_gallery_thumbnail_number = 3
 plotter.plot_qps_vs_e0(tight_layout=True)
diff --git a/abipy/examples/plot/plot_qpmarkers.py b/abipy/examples/plot/plot_qpmarkers.py
index bc74720a..a7f1d96a 100755
--- a/abipy/examples/plot/plot_qpmarkers.py
+++ b/abipy/examples/plot/plot_qpmarkers.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+AbiPy examples
+==============
+
 This example shows how to plot the Kohn-Sham energies with
 markers providing a graphical representation of the GW results.
 """
diff --git a/abipy/examples/plot/plot_qps.py b/abipy/examples/plot/plot_qps.py
index acfe2726..84475c2a 100755
--- a/abipy/examples/plot/plot_qps.py
+++ b/abipy/examples/plot/plot_qps.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+SIGRES file (GW)
+================
+
 This example shows how to visualize the QP results 
 stored in the SIGRES produced by the GW code (sigma run)
 """
diff --git a/abipy/examples/plot/plot_qpscfgw.py b/abipy/examples/plot/plot_qpscfgw.py
index 58e2d5bf..c6d56c77 100755
--- a/abipy/examples/plot/plot_qpscfgw.py
+++ b/abipy/examples/plot/plot_qpscfgw.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+self-consistent GW
+==================
+
 This example shows how to visualize the SCGW QP amplitudes in the KS basis set.
 """
 import abipy.data as abidata
diff --git a/abipy/examples/plot/plot_scr.py b/abipy/examples/plot/plot_scr.py
index d9ee875c..5ad2db3f 100755
--- a/abipy/examples/plot/plot_scr.py
+++ b/abipy/examples/plot/plot_scr.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Dielectric function with LFE
+============================
+
 This examples shows how to plot the macroscopic dielectric function
 computed in the GW code (optdriver 3)
 """
@@ -14,6 +17,7 @@ with abiopen(abidata.ref_file("sio2_SCR.nc")) as ncfile:
     edos = ncfile.ebands.get_edos()
     ncfile.ebands.plot_with_edos(edos, title="KS energies used to compute the SCR file.")
 
+    # sphinx_gallery_thumbnail_number = 2
     ncfile.plot_emacro(title="Macroscopic dielectric function of $SiO_2$ with local-field effects.")
 
     ncfile.plot_eelf(title="Electron Energy Loss Function of $SiO_2$")
diff --git a/abipy/examples/plot/plot_scr_matrix.py b/abipy/examples/plot/plot_scr_matrix.py
index 3a4908cf..90a81485 100755
--- a/abipy/examples/plot/plot_scr_matrix.py
+++ b/abipy/examples/plot/plot_scr_matrix.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+SCF matrix
+==========
+
 This examples shows how to plot the matrix elements of the 
 inverse dielectric function stored in the SCR file (optdriver 3)
 See also `plot_scr.py` for the optical spectrum.
diff --git a/abipy/examples/plot/plot_sigmaw.py b/abipy/examples/plot/plot_sigmaw.py
index fe63234b..96b87c16 100755
--- a/abipy/examples/plot/plot_sigmaw.py
+++ b/abipy/examples/plot/plot_sigmaw.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+GW and spectral function
+========================
+
 This examples shows how to plot the GW self-energy
 and the spectral function of Al at the gamma point (first band)
 See lesson tgw2_4
diff --git a/abipy/examples/plot/plot_spectral_functions.py b/abipy/examples/plot/plot_spectral_functions.py
index 4cf0129d..1f5135bb 100755
--- a/abipy/examples/plot/plot_spectral_functions.py
+++ b/abipy/examples/plot/plot_spectral_functions.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+G0W0 spectral function
+======================
+
 This examples shows how to plot the G0W0 spectral functions A(w)
 at the gamma point, for the first band). See lesson tgw2_4
 """
diff --git a/abipy/examples/plot/plot_wfk.py b/abipy/examples/plot/plot_wfk.py
index f0eccb31..af2b7a59 100755
--- a/abipy/examples/plot/plot_wfk.py
+++ b/abipy/examples/plot/plot_wfk.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+Wavefunction file
+=================
+
 This example shows how to analyze the wavefunctions
 stored in the WFK.nc file.
 """
diff --git a/abipy/examples/plot/plot_xrd.py b/abipy/examples/plot/plot_xrd.py
index cdb95248..aa9f542f 100755
--- a/abipy/examples/plot/plot_xrd.py
+++ b/abipy/examples/plot/plot_xrd.py
@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-"""
+r"""
+X-ray diffraction pattern
+=========================
+
 This example shows how to plot the X-ray diffraction pattern with pymatgen
 """
 from abipy import abilab 
diff --git a/docs/Makefile b/docs/Makefile
index 35c080f4..08f7f238 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -42,6 +42,7 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf gallery/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -153,3 +154,11 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+livehtml:
+	sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
diff --git a/docs/conf.py b/docs/conf.py
index 2020bf59..4f587738 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -39,7 +39,7 @@ extensions = [
 'sphinx.ext.autodoc',
 'sphinx.ext.doctest',
 #'sphinx.ext.coverage',
-#'sphinx.ext.autosummary',
+'sphinx.ext.autosummary',
 'sphinx.ext.intersphinx',
 'sphinx.ext.todo',
 'sphinx.ext.coverage',
@@ -50,9 +50,9 @@ extensions = [
 'sphinx.ext.napoleon',   # For Google Python Style Guide
 'sphinx.ext.inheritance_diagram',
 'sphinxcontrib.programoutput',
+'sphinx_gallery.gen_gallery',
 #'sphinxcontrib.autoprogram',
 #"sphinxcontrib.argdoc", # slow but nice
-#'sphinx_gallery.gen_gallery',
 ]
 
 # Add any Sphinx extension module names here, as strings. They can
@@ -66,12 +66,25 @@ extensions += [
           'IPython.sphinxext.ipython_console_highlighting',
           # This does not work with py3k
           #'numpydoc',
-          'gen_rst',
+          #'gen_rst',
           #'sphinxcontrib.autorun',
-          'autorun',
-          #'gen_gallery',  Generate gallery of PICS a la' matplotlib.
+          #'autorun',
           ]
 
+
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    'examples_dirs': '../abipy/examples/plot',
+    # path where to save gallery generated examples
+    'gallery_dirs': 'gallery',
+    #'filename_pattern': '/plot_',
+    'backreferences_dir': False,
+    'reference_url': {
+        # The module you locally document uses None
+        'abipy': None,
+    }
+}
+
 # Generate the API documentation when building
 autosummary_generate = True
 numpydoc_show_class_members = False
@@ -89,8 +102,8 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'abipy'
-copyright = u'2017, ' + relmod.author
+project = 'abipy'
+copyright = '2017, ' + relmod.author
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -143,13 +156,86 @@ import sphinx_bootstrap_theme
 html_theme = 'bootstrap'
 html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
+# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24).
+# Path should be relative to the ``_static`` files directory.
+#html_logo = "my_logo.png"
+
+# Theme options are theme-specific and customize the look and feel of a
+# theme further.
+html_theme_options = {
+    # Navigation bar title. (Default: ``project`` value)
+    #'navbar_title': "Demo",
+
+    # Tab name for entire site. (Default: "Site")
+    'navbar_site_name': "Site",
+
+    # A list of tuples containing pages or urls to link to.
+    # Valid tuples should be in the following forms:
+    #    (name, page)                 # a link to a page
+    #    (name, "/aa/bb", 1)          # a link to an arbitrary relative url
+    #    (name, "http://example.com", True) # arbitrary absolute url
+    # Note the "1" or "True" value above as the third argument to indicate
+    # an arbitrary url.
+    #'navbar_links': [
+    #    ("Examples", "examples"),
+    #    ("Link", "http://example.com", True),
+    #],
+
+    # Render the next and previous page links in navbar. (Default: true)
+    'navbar_sidebarrel': True,
+
+    # Render the current pages TOC in the navbar. (Default: true)
+    'navbar_pagenav': True,
+
+    # Tab name for the current pages TOC. (Default: "Page")
+    'navbar_pagenav_name': "Page",
+
+    # Global TOC depth for "site" navbar tab. (Default: 1)
+    # Switching to -1 shows all levels.
+    'globaltoc_depth': 1,
+
+    # Include hidden TOCs in Site navbar?
+    #
+    # Note: If this is "false", you cannot have mixed ``:hidden:`` and
+    # non-hidden ``toctree`` directives in the same page, or else the build
+    # will break.
+    #
+    # Values: "true" (default) or "false"
+    'globaltoc_includehidden': "true",
+
+    # HTML navbar class (Default: "navbar") to attach to <div> element.
+    # For black navbar, do "navbar navbar-inverse"
+    #'navbar_class': "navbar navbar-inverse",
+
+    # Fix navigation bar to top of page?
+    # Values: "true" (default) or "false"
+    'navbar_fixed_top': "true",
+
+    # Location of link to source.
+    # Options are "nav" (default), "footer" or anything else to exclude.
+    'source_link_position': "nav",
+
+    # Bootswatch (http://bootswatch.com/) theme.
+    # Options are nothing (default) or the name of a valid theme
+    # such as "cosmo" or "sandstone".
+    #'bootswatch_theme': "united",
+    #'bootswatch_theme': "flatly",
+    #'bootswatch_theme': "litera",
+    #'bootswatch_theme': "simplex",
+    #'bootswatch_theme': "sandstone",
+
+    # Choose Bootstrap version.
+    # Values: "3" (default) or "2" (in quotes)
+    'bootstrap_version': "3",
+}
+
+"""
 # The theme to use for HTML and HTML Help pages.  See the documentation for a list of builtin themes.
 #html_theme = 'default'
 #html_theme = "sphinxdoc"
 #html_theme = "agogo"
 #html_theme = "scrolls"
 
-"""
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the documentation.
 # http://alabaster.readthedocs.io/en/latest/customization.html
@@ -176,9 +262,8 @@ html_theme_options = {
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-html_logo = "_static/abipy_logo.png"
+# The name of an image file (relative to this directory) to place at the top of the sidebar.
+#html_logo = "_static/abipy_logo.png"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -254,7 +339,7 @@ latex_documents = [
   ('index',
    'abipy.tex',
    'AbiPy Documentation',
-   u'M. Giantomassi',
+   'M. Giantomassi',
    'manual'),
 ]
 
@@ -284,7 +369,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'abipy', u'abipy Documentation',
+    ('index', 'abipy', 'abipy Documentation',
      ", ".join(list(a[0] for a in relmod.authors.values())), 1)
 ]
 
@@ -298,8 +383,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'abipy', u'abipy Documentation',
-   u'M. Giantomassi', 'abipy', 'One line description of project.',
+  ('index', 'abipy', 'abipy Documentation',
+   'M. Giantomassi', 'abipy', 'One line description of project.',
    'Miscellaneous'),
 ]
 
@@ -312,7 +397,6 @@ texinfo_documents = [
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/2', None),
diff --git a/docs/index.rst b/docs/index.rst
index 38c9ca60..8d8fb50e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,19 +1,19 @@
-.. image:: https://badge.fury.io/py/abipy.svg
-        :target: https://badge.fury.io/py/abipy
-
-.. image:: https://travis-ci.org/abinit/abipy.svg?branch=master
-        :target: https://travis-ci.org/abinit/abipy
-
-.. image:: https://coveralls.io/repos/github/abinit/abipy/badge.svg?branch=develop
-        :target: https://coveralls.io/github/abinit/abipy?branch=develop
-
-.. image:: https://img.shields.io/badge/license-GPL-blue.svg
-
 .. htmlonly::
 
     :Release: |version|
     :Date: |today|
 
+.. image:: https://badge.fury.io/py/abipy.svg
+    :target: https://badge.fury.io/py/abipy
+
+.. image:: https://travis-ci.org/abinit/abipy.svg?branch=master
+    :target: https://travis-ci.org/abinit/abipy
+
+.. image:: https://coveralls.io/repos/github/abinit/abipy/badge.svg?branch=develop
+    :target: https://coveralls.io/github/abinit/abipy?branch=develop
+
+.. image:: https://img.shields.io/badge/license-GPL-blue.svg
+
 Getting Started
 ===============
 
@@ -28,13 +28,13 @@ Post-processing
 ===============
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    scripts
-   examples/plot/index.rst
+   gallery/index.rst
 
-Calculations
-============
+Workflows
+=========
 
 .. toctree::
    :maxdepth: 1