From 8807bce012246fff060a8614e928246efc13efbe Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Mon, 31 Jul 2017 15:40:12 -0600
Subject: [PATCH 1/8] WIP: Update docs

---
 README.rst                     |   6 +-
 doc/advanced_configuration.rst | 165 +++++++++++++++++++--------------
 doc/getting_started.rst        |  14 ---
 3 files changed, 98 insertions(+), 87 deletions(-)

diff --git a/README.rst b/README.rst
index 13633528d..9b0d31bb9 100644
--- a/README.rst
+++ b/README.rst
@@ -1,6 +1,6 @@
-=================================
-Getting Started to Sphinx-Gallery
-=================================
+===================================
+Getting Started with Sphinx-Gallery
+===================================
 
 .. image:: https://travis-ci.org/sphinx-gallery/sphinx-gallery.svg?branch=master
     :target: https://travis-ci.org/sphinx-gallery/sphinx-gallery
diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index 4a71add2e..1fde90698 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -1,29 +1,49 @@
-======================
-Advanced Configuration
-======================
+=============
+Configuration
+=============
 
-Here are the personal configurations that you can modify within Sphinx-Gallery.
+Most sphinx-gallery configuration options are set in the Sphinx ``conf.py``
+file:
+
+- `examples_dirs and gallery_dirs <multiple_galleries_config>`_
+- `filename_pattern <build_pattern>`_
+- `subsection_order <sub_gallery_order>`_
+- `reference_url` <link_to_documentation>`_
+- `backreferences_dir and doc_module <references_to_examples> `_
+- `default_thumb_file <custom_default_thumb>`_
+- `line_numbers <adding_line_numbers>`_
+- `disable_joint_download <download_section_examples>`_
+
+Some options can also be set or overridden on a file-by-file basis:
+
+- adding_line_numbers_
+- without_execution_
+- choosing_thumbnail_
+
+And some options can be set during the build execution step:
+
+- without_execution_
+- dealing_with_failures_
 
 .. _multiple_galleries_config:
 
-Manage Multiple galleries
-=========================
+Managing multiple galleries
+===========================
 
 Sphinx-Gallery only supports up to sub-folder level in its gallery directories.
 This might be a limitation for you. Or you might want to have separate
 galleries for different purposes, an examples gallery and a tutorials gallery.
 For this you use in your Sphinx ``conf.py`` file a list of directories in
-the sphinx configuration dictionary:
-
-.. code-block:: python
+the sphinx configuration dictionary::
 
     sphinx_gallery_conf = {
-        'examples_dirs'   : ['../examples', '../tutorials'],
-        'gallery_dirs'    : ['auto_examples', 'tutorials'],
+        'examples_dirs': ['../examples', '../tutorials'],
+        'gallery_dirs': ['auto_examples', 'tutorials'],
     }
 
 Keep in mind that both lists have to be of the same length.
 
+
 .. _build_pattern:
 
 Building examples matching a pattern
@@ -36,7 +56,7 @@ in your Sphinx ``conf.py``. For example:
 .. code-block:: python
 
     sphinx_gallery_conf = {
-        'filename_pattern'  : '/plot_compute_'
+        'filename_pattern': '/plot_compute_',
     }
 
 will build all examples starting with ``plot_compute_``. The key ``filename_pattern`` accepts
@@ -46,37 +66,32 @@ they want to be agnostic to the operating system.
 
 This option is also useful if you want to build only a subset of the examples. For example, you may
 want to build only one example so that you can link it in the documentation. In that case,
-you would do:
-
-.. code-block:: python
+you would do::
 
     sphinx_gallery_conf = {
-        'filename_pattern' : 'plot_awesome_example.py'
+        'filename_pattern': 'plot_awesome_example.py',
     }
 
 Here, one should escape the dot ``'\.'`` as otherwise python `regular expressions`_ matches any character. Nevertheless, as
 one is targeting a specific file, it is most certainly going to match the dot in the filename.
 
-Similarly, to build only examples in a specific directory, you can do:
-
-.. code-block:: python
+Similarly, to build only examples in a specific directory, you can do::
 
     sphinx_gallery_conf = {
-        'filename_pattern' : '/directory/plot_'
+        'filename_pattern': '/directory/plot_',
     }
 
 Alternatively, you can skip some examples. For example, to skip building examples
-starting with ``plot_long_examples_``, you would do:
-
-.. code-block:: python
+starting with ``plot_long_examples_``, you would do::
 
     sphinx_gallery_conf = {
-        'filename_pattern' : '/plot_(?!long_examples)'
+        'filename_pattern': '/plot_(?!long_examples)',
     }
 
 As the patterns are parsed as `regular expressions`_, users are advised to consult the
 `regular expressions`_ module for more details.
 
+
 .. _sub_gallery_order:
 
 Sorting the subsections inside a gallery
@@ -86,9 +101,7 @@ Gallery subsections are sorted by default alphabetically by their folder
 name, and as such you can always organize them by changing your folder
 names. An alternative option is to use a sortkey to organize those
 subsections. We provide an explicit order sortkey where you have to define
-the order of all subfolders in your galleries.
-
-.. code-block:: python
+the order of all subfolders in your galleries::
 
     from sphinx_gallery.sorting import ExplicitOrder
     sphinx_gallery_conf = {
@@ -133,18 +146,16 @@ Have a look at this in full action
 in our example :ref:`sphx_glr_auto_examples_plot_gallery_version.py`.
 
 To make this work in your documentation you need to include to the configuration
-dictionary within your Sphinx ``conf.py`` file :
-
-.. code-block:: python
+dictionary within your Sphinx ``conf.py`` file::
 
     sphinx_gallery_conf = {
-        'reference_url':  {
+        'reference_url': {
                  # The module you locally document uses a None
                 'sphinx_gallery': None,
 
                 # External python modules use their documentation websites
                 'matplotlib': 'https://matplotlib.org',
-                'numpy': 'https://docs.scipy.org/doc/numpy'}
+                'numpy': 'https://docs.scipy.org/doc/numpy'},
         }
 
 
@@ -165,11 +176,8 @@ looks like this:
         <div style='clear:both'></div>
 
 
-
 For such behavior to be available, you have to activate it in your
-Sphinx-Gallery configuration ``conf.py`` file with:
-
-.. code-block:: python
+Sphinx-Gallery configuration ``conf.py`` file with::
 
     sphinx_gallery_conf = {
         # directory where function granular galleries are stored
@@ -202,16 +210,14 @@ is in the same directory as ``conf.py``) we directly use the path
 declared in ``backreferences_dir`` followed by the function whose
 examples we want to show and the file has the ``.examples`` extension.
 
-Auto documenting your API with links to examples
+Auto-documenting your API with links to examples
 ------------------------------------------------
 
 The previous feature can be automated for all your modules combining
 it with the standard sphinx extensions `autodoc
 <http://sphinx-doc.org/ext/autodoc.html>`_ and `autosummary
 <http://sphinx-doc.org/ext/autosummary.html>`_. First enable them in your
-``conf.py`` extensions list.
-
-.. code-block:: python
+``conf.py`` extensions list::
 
     import sphinx_gallery
     extensions = [
@@ -262,20 +268,59 @@ configuration option setup for Sphinx-Gallery.
     :linenos:
 
 
+.. _custom_default_thumb:
+
 Using a custom default thumbnail image
 ======================================
 
 In case you want to use your own image for the thumbnail of examples that do
 not generate any plot, you can specify it by editing your Sphinx ``conf.py``
 file. You need to add to the configuration dictionary a key called
-`default_thumb_file`. For example:
+`default_thumb_file`. For example::
 
-.. code-block:: python
+    sphinx_gallery_conf = {
+        'default_thumb_file': 'path/to/thumb/file.png',
+    }
+
+
+.. _adding_line_numbers:
+
+Adding line numbers to example listings
+=======================================
+
+Line numbers can be displayed in listings by adding the global ``line_numbers``
+setting::
+
+    sphinx_gallery_conf = {
+        'line_numbers': True,
+    }
+
+or by adding a comment to the example script, which overrides any global
+setting::
+
+    # sphinx_gallery_line_numbers = True
+
+Note that for Sphinx < 1.3, the line numbers will not be consistent with the
+original file.
+
+
+.. _disable_joint_download:
+
+Disable joint download of all gallery scripts
+=============================================
+
+By default Sphinx-Gallery prepares zip files of all python scripts and
+all Jupyter notebooks for each gallery section and makes them
+available for download at the end of each section. To disable this
+behavior add to the configuration dictionary in your ``conf.py`` file::
 
     sphinx_gallery_conf = {
-        'default_thumb_file'     : 'path/to/thumb/file.png'}}
+        'download_section_examples': False,
+    }
 
 
+.. _choosing_thumbnail:
+
 Choosing the thumbnail image from multiple figures
 ==================================================
 
@@ -284,9 +329,7 @@ the first figure created in each as the thumbnail image displayed in the
 gallery. To change the thumbnail image to a figure generated later in
 an example script, add a comment to the example script to specify the
 number of the figure you would like to use as the thumbnail. For example,
-to use the 2nd figure created as the thumbnail:
-
-.. code-block:: python
+to use the 2nd figure created as the thumbnail::
 
     # sphinx_gallery_thumbnail_number = 2
 
@@ -294,8 +337,11 @@ The default behavior is ``sphinx_gallery_thumbnail_number = 1``. See
 :ref:`sphx_glr_auto_examples_plot_choose_thumbnail.py` for an example
 of this functionality.
 
-Build the Gallery without executing the examples
-================================================
+
+.. _without_execution:
+
+Building the Gallery without executing the examples
+===================================================
 
 Sphinx-Gallery can parse all your examples and build the gallery
 without executing any of the scripts. This is just for speed
@@ -318,28 +364,7 @@ configuration file to have it as a default. The highest precedence is
 always given to the `-D` flag of the ``sphinx-build`` command.
 
 
-Adding line numbers to example listings
-=======================================
-
-Line numbers can be displayed in listings by adding the global ``line_numbers``
-setting:
-
-.. code-block:: python
-
-    sphinx_gallery_conf = {
-        'line_numbers': True
-    }
-
-or by adding a comment to the example script, which overrides any global
-setting:
-
-.. code-block:: python
-
-    # sphinx_gallery_line_numbers = True
-
-Note that for Sphinx < 1.3, the line numbers will not be consistent with the
-original file.
-
+.. _dealing_with_failures:
 
 Dealing with failing Gallery example scripts
 ============================================
diff --git a/doc/getting_started.rst b/doc/getting_started.rst
index c57130c0e..f5413ad67 100644
--- a/doc/getting_started.rst
+++ b/doc/getting_started.rst
@@ -1,6 +1,5 @@
 .. include:: ../README.rst
 
-
 Know your Gallery files
 =======================
 
@@ -21,16 +20,3 @@ its reference
 ``:ref:`sphx_glr_auto_examples_plot_gallery_version.py```. The image
 it generated has the name ``sphx_glr_plot_gallery_version_thumb.png``
 and its thumbnail is ``sphx_glr_plot_gallery_version_thumb.png``
-
-Disable joint download of all gallery scripts
----------------------------------------------
-
-By default Sphinx-Gallery prepares zip files of all python scripts and
-all Jupyter notebooks for each gallery section and makes them
-available for download at the end of each section. To disable this
-behavior add to the configuration dictionary in your ``conf.py`` file
-
-.. code-block:: python
-
-    sphinx_gallery_conf = {
-	'download_section_examples'  : False}

From 3361d655ff16c5d593459c3c48a45ac9b5a796ba Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Mon, 31 Jul 2017 16:01:51 -0600
Subject: [PATCH 2/8] FIX: Use refs not links

---
 README.rst                     | 29 +++++++++------
 doc/advanced_configuration.rst | 65 ++++++++++++++++------------------
 2 files changed, 49 insertions(+), 45 deletions(-)

diff --git a/README.rst b/README.rst
index 9b0d31bb9..eb6a17769 100644
--- a/README.rst
+++ b/README.rst
@@ -34,11 +34,14 @@ Who uses Sphinx-Gallery
 * `scikit-image <http://scikit-image.org/docs/dev/auto_examples/>`_
 * `Astropy <http://docs.astropy.org/en/stable/generated/examples/index.html>`_
 * `SunPy <http://docs.sunpy.org/en/stable/generated/gallery/index.html>`_
+* `PySurfer <https://pysurfer.github.io/>`_
 
 Getting the package
 ===================
 
-You can do a direct install via pip by using::
+You can do a direct install via pip by using:
+
+.. code-block:: bash
 
     $ pip install sphinx-gallery
 
@@ -64,7 +67,9 @@ You can get the latest development source from our `Github repository
 
 You will also need to install the dependencies listed above and `pytest`
 
-To install everything do::
+To install everything do:
+
+.. code-block:: bash
 
     $ git clone https://github.com/sphinx-gallery/sphinx-gallery
     $ cd sphinx-gallery
@@ -103,9 +108,7 @@ structure you get from executing ``sphinx-quickstart``.
 
 
 To get Sphinx-Gallery into your project we have to extend the Sphinx
-``doc/conf.py`` file with:
-
-.. code-block:: python
+``doc/conf.py`` file with::
 
     extensions = [
         ...
@@ -117,9 +120,7 @@ This is to load Sphinx-Gallery as one of your extensions, the ellipsis
 
 Now to declare your project structure, we add a configuration
 dictionary for Sphinx-Gallery. The examples directory ``../examples``
-is declared with a relative path from the ``conf.py`` file location.
-
-.. code-block:: python
+is declared with a relative path from the ``conf.py`` file location::
 
     sphinx_gallery_conf = {
 	# path to your examples scripts
@@ -157,7 +158,9 @@ files.
 Building the documentation locally
 ----------------------------------
 
-In your sphinx documentation directory, ``doc`` execute::
+In your sphinx documentation directory, ``doc`` execute:
+
+.. code-block:: bash
 
     $ make html
 
@@ -165,7 +168,9 @@ This will start the build of your complete documentation including the examples
 gallery. Once documentation is build, our extension will have generated an ``auto_examples``
 directory and populated it with rst files containing the gallery and each example.
 Sphinx gives this files its regular processing and you can enjoy your
-generated gallery under the same path. That means you will find the gallery in the path::
+generated gallery under the same path. That means you will find the gallery in the path:
+
+.. code-block:: bash
 
     _build/html/auto_examples/index.html
 
@@ -181,7 +186,9 @@ Extending your Makefile
 -----------------------
 Once your gallery is working you might need remove completely all generated files by
 sphinx-gallery to have a clean build, or you might want to build the gallery without
-running the examples files. For this you need to extend your ``Makefile`` with::
+running the examples files. For this you need to extend your ``Makefile`` with:
+
+.. code-block:: bash
 
     clean:
             rm -rf $(BUILDDIR)/*
diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index 1fde90698..6f6e5fda6 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -2,28 +2,31 @@
 Configuration
 =============
 
+List of config options
+======================
+
 Most sphinx-gallery configuration options are set in the Sphinx ``conf.py``
 file:
 
-- `examples_dirs and gallery_dirs <multiple_galleries_config>`_
-- `filename_pattern <build_pattern>`_
-- `subsection_order <sub_gallery_order>`_
-- `reference_url` <link_to_documentation>`_
-- `backreferences_dir and doc_module <references_to_examples> `_
-- `default_thumb_file <custom_default_thumb>`_
-- `line_numbers <adding_line_numbers>`_
-- `disable_joint_download <download_section_examples>`_
+- :ref:`examples_dirs and gallery_dirs <multiple_galleries_config>`
+- :ref:`filename_pattern <build_pattern>`
+- :ref:`subsection_order <sub_gallery_order>`
+- :ref:`reference_url <link_to_documentation>`
+- :ref:`backreferences_dir and doc_module <references_to_examples>`
+- :ref:`default_thumb_file <custom_default_thumb>`
+- :ref:`line_numbers <adding_line_numbers>`
+- :ref:`disable_joint_download <download_section_examples>`
 
 Some options can also be set or overridden on a file-by-file basis:
 
-- adding_line_numbers_
-- without_execution_
-- choosing_thumbnail_
+- :ref:`adding_line_numbers`
+- :ref:`without_execution`
+- :ref:`choosing_thumbnail`
 
 And some options can be set during the build execution step:
 
-- without_execution_
-- dealing_with_failures_
+- :ref:`without_execution`
+- :ref:`dealing_with_failures`
 
 .. _multiple_galleries_config:
 
@@ -51,9 +54,7 @@ Building examples matching a pattern
 
 By default, Sphinx-Gallery execute only examples beginning with ``plot``. However,
 if this naming convention does not suit your project, you can modify this pattern
-in your Sphinx ``conf.py``. For example:
-
-.. code-block:: python
+in your Sphinx ``conf.py``. For example::
 
     sphinx_gallery_conf = {
         'filename_pattern': '/plot_compute_',
@@ -94,8 +95,7 @@ As the patterns are parsed as `regular expressions`_, users are advised to consu
 
 .. _sub_gallery_order:
 
-Sorting the subsections inside a gallery
-========================================
+Sorting gallery subsections
 
 Gallery subsections are sorted by default alphabetically by their folder
 name, and as such you can always organize them by changing your folder
@@ -161,8 +161,8 @@ dictionary within your Sphinx ``conf.py`` file::
 
 .. _references_to_examples:
 
-References to examples (backreferences)
-=======================================
+Adding references to examples
+=============================
 
 Sphinx-Gallery enables you, when documenting your modules, to
 reference to the examples that use a particular function. For example
@@ -270,8 +270,8 @@ configuration option setup for Sphinx-Gallery.
 
 .. _custom_default_thumb:
 
-Using a custom default thumbnail image
-======================================
+Using a custom default thumbnail
+================================
 
 In case you want to use your own image for the thumbnail of examples that do
 not generate any plot, you can specify it by editing your Sphinx ``conf.py``
@@ -285,8 +285,8 @@ file. You need to add to the configuration dictionary a key called
 
 .. _adding_line_numbers:
 
-Adding line numbers to example listings
-=======================================
+Adding line numbers to examples
+===============================
 
 Line numbers can be displayed in listings by adding the global ``line_numbers``
 setting::
@@ -306,8 +306,8 @@ original file.
 
 .. _disable_joint_download:
 
-Disable joint download of all gallery scripts
-=============================================
+Disabling joint download of scripts
+===================================
 
 By default Sphinx-Gallery prepares zip files of all python scripts and
 all Jupyter notebooks for each gallery section and makes them
@@ -321,8 +321,8 @@ behavior add to the configuration dictionary in your ``conf.py`` file::
 
 .. _choosing_thumbnail:
 
-Choosing the thumbnail image from multiple figures
-==================================================
+Choosing the thumbnail image
+============================
 
 For examples that generate multiple figures, the default behavior will use
 the first figure created in each as the thumbnail image displayed in the
@@ -340,8 +340,8 @@ of this functionality.
 
 .. _without_execution:
 
-Building the Gallery without executing the examples
-===================================================
+Building without executing examples
+===================================
 
 Sphinx-Gallery can parse all your examples and build the gallery
 without executing any of the scripts. This is just for speed
@@ -417,10 +417,7 @@ It might be the case that you want to keep the gallery even with
 failed examples. Thus you can configure Sphinx-Gallery to allow
 certain examples to fail and still exit with a 0 exit code. For this
 you need to list all the examples you want to allow to fail during
-build. Change your `conf.py` accordingly:
-
-
-.. code-block:: python
+build. Change your `conf.py` accordingly::
 
     sphinx_gallery_conf = {
         ...

From 62aeee154c37b02542c27ae7138893a1fb279fdf Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Mon, 31 Jul 2017 16:33:24 -0600
Subject: [PATCH 3/8] FIX: Many fixes

---
 doc/advanced_configuration.rst | 86 ++++++++++++++++++++++++++--------
 1 file changed, 66 insertions(+), 20 deletions(-)

diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index 6f6e5fda6..9e970338d 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -8,25 +8,32 @@ List of config options
 Most sphinx-gallery configuration options are set in the Sphinx ``conf.py``
 file:
 
-- :ref:`examples_dirs and gallery_dirs <multiple_galleries_config>`
-- :ref:`filename_pattern <build_pattern>`
-- :ref:`subsection_order <sub_gallery_order>`
-- :ref:`reference_url <link_to_documentation>`
-- :ref:`backreferences_dir and doc_module <references_to_examples>`
-- :ref:`default_thumb_file <custom_default_thumb>`
-- :ref:`line_numbers <adding_line_numbers>`
-- :ref:`disable_joint_download <download_section_examples>`
+- ``examples_dirs`` and ``gallery_dirs`` (:ref:`multiple_galleries_config`)
+- ``filename_pattern`` (:ref:`build_pattern`)
+- ``subsection_order`` (:ref:`sub_gallery_order`)
+- ``reference_url`` (:ref:`link_to_documentation`)
+- ``backreferences_dir` and ``doc_module`` (:ref:`references_to_examples`)
+- ``default_thumb_file`` (:ref:`custom_default_thumb`)
+- ``line_numbers`` (:ref:`adding_line_numbers`)
+- ``download_section_examples`` (:ref:`disable_joint_download`)
+- ``plot_gallery`` (:ref:`without_execution`)
+- ``abort_on_example_error`` (:ref:`abort_on_first`)
+- ``expected_failing_examples`` (:ref:`dont_fail_exit`)
 
 Some options can also be set or overridden on a file-by-file basis:
 
-- :ref:`adding_line_numbers`
-- :ref:`without_execution`
-- :ref:`choosing_thumbnail`
+- ``# sphinx_gallery_line_numbers`` (:ref:`adding_line_numbers`)
+- ``# sphinx_gallery_thumbnail_number`` (:ref:`choosing_thumbnail`)
 
-And some options can be set during the build execution step:
+Some options can be set during the build execution step, e.g. using a Makefile:
+
+- ``make html-noplot`` (:ref:`without_execution`)
+- ``make html_abort_on_example_error`` (:ref:`abort_on_first`)
+
+And some things can be tweaked directly in CSS:
+
+- ``.sphx-glr-thumbcontainer`` (:ref:`setting_thumbnail_size`)
 
-- :ref:`without_execution`
-- :ref:`dealing_with_failures`
 
 .. _multiple_galleries_config:
 
@@ -359,12 +366,16 @@ Remember that for ``Makefile`` white space is significant and the indentation ar
 and not spaces.
 
 Alternatively, you can add the ``plot_gallery`` option to the
-``sphinx_gallery_conf`` dictionary inside your ``conf.py``
-configuration file to have it as a default. The highest precedence is
-always given to the `-D` flag of the ``sphinx-build`` command.
+``sphinx_gallery_conf`` dictionary inside your ``conf.py`` to have it as
+a default::
+
+    sphinx_gallery_conf = {
+        'plot_gallery': False,
+    }
 
+The highest precedence is always given to the `-D` flag of the
+``sphinx-build`` command.
 
-.. _dealing_with_failures:
 
 Dealing with failing Gallery example scripts
 ============================================
@@ -387,6 +398,8 @@ easily.
 
 There are some additional options at your hand to deal with broken examples.
 
+.. _abort_on_first:
+
 Abort build on first fail
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -406,9 +419,17 @@ and not spaces.
 
 Alternatively, you can add the ``abort_on_example_error`` option to
 the ``sphinx_gallery_conf`` dictionary inside your ``conf.py``
-configuration file to have it as a default. The highest precedence is
-always given to the `-D` flag of the ``sphinx-build`` command.
+configuration file to have it as a default::
+
+    sphinx_gallery_conf = {
+        'abort_on_example_error': True,
+    }
+
 
+The highest precedence is always given to the `-D` flag of
+the ``sphinx-build`` command.
+
+.. _dont_fail_exit:
 
 Don't fail the build on exit
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -429,4 +450,29 @@ keep in mind to specify the full relative path from your `conf.py` to
 the example script.
 
 
+.. _setting_thumbnail_size:
+
+Setting gallery thumbnail size
+==============================
+
+The gallery uses various CSS classes in the gallery. For example, to use
+images that are at most 250x250px, you can do something like:
+
+.. code-block:: css
+
+    .sphx-glr-thumbcontainer {
+        min-height: 300px;
+    }
+    .sphx-glr-thumbcontainer .figure {
+        width: 250px;
+    }
+    .sphx-glr-thumbcontainer img {
+        max-height: 250px;
+        width: 250px;
+    }
+    .sphx-glr-thumbcontainer a.internal {
+        padding: 210px
+    }
+
+
 .. _regular expressions: https://docs.python.org/2/library/re.html

From f697e54127f7f3188699600a2c1b33d3784b05ed Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Mon, 31 Jul 2017 16:41:50 -0600
Subject: [PATCH 4/8] FIX: Fix typos

---
 doc/advanced_configuration.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index 9e970338d..f86e9bf08 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -12,7 +12,7 @@ file:
 - ``filename_pattern`` (:ref:`build_pattern`)
 - ``subsection_order`` (:ref:`sub_gallery_order`)
 - ``reference_url`` (:ref:`link_to_documentation`)
-- ``backreferences_dir` and ``doc_module`` (:ref:`references_to_examples`)
+- ``backreferences_dir`` and ``doc_module`` (:ref:`references_to_examples`)
 - ``default_thumb_file`` (:ref:`custom_default_thumb`)
 - ``line_numbers`` (:ref:`adding_line_numbers`)
 - ``download_section_examples`` (:ref:`disable_joint_download`)
@@ -103,6 +103,7 @@ As the patterns are parsed as `regular expressions`_, users are advised to consu
 .. _sub_gallery_order:
 
 Sorting gallery subsections
+===========================
 
 Gallery subsections are sorted by default alphabetically by their folder
 name, and as such you can always organize them by changing your folder
@@ -401,7 +402,7 @@ There are some additional options at your hand to deal with broken examples.
 .. _abort_on_first:
 
 Abort build on first fail
-^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------
 
 Sphinx-Gallery provides the early fail option. In
 this mode the gallery build process breaks as soon as an exception
@@ -432,7 +433,7 @@ the ``sphinx-build`` command.
 .. _dont_fail_exit:
 
 Don't fail the build on exit
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
 
 It might be the case that you want to keep the gallery even with
 failed examples. Thus you can configure Sphinx-Gallery to allow
@@ -456,7 +457,8 @@ Setting gallery thumbnail size
 ==============================
 
 The gallery uses various CSS classes in the gallery. For example, to use
-images that are at most 250x250px, you can do something like:
+images that are at most 250x250px, you can modify the default CSS
+with something like:
 
 .. code-block:: css
 

From 49bb6ef9e10aa7c9e6133c93e5e96bd7ced03ef9 Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Mon, 31 Jul 2017 16:55:21 -0600
Subject: [PATCH 5/8] FIX: Fix doc

---
 doc/advanced_configuration.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index f86e9bf08..2c21623d9 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -219,7 +219,7 @@ declared in ``backreferences_dir`` followed by the function whose
 examples we want to show and the file has the ``.examples`` extension.
 
 Auto-documenting your API with links to examples
-------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The previous feature can be automated for all your modules combining
 it with the standard sphinx extensions `autodoc
@@ -402,7 +402,7 @@ There are some additional options at your hand to deal with broken examples.
 .. _abort_on_first:
 
 Abort build on first fail
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sphinx-Gallery provides the early fail option. In
 this mode the gallery build process breaks as soon as an exception
@@ -433,7 +433,7 @@ the ``sphinx-build`` command.
 .. _dont_fail_exit:
 
 Don't fail the build on exit
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 It might be the case that you want to keep the gallery even with
 failed examples. Thus you can configure Sphinx-Gallery to allow

From ea0a6bd9f42a4a3992922e96998a263582e366ba Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Tue, 1 Aug 2017 10:02:47 -0600
Subject: [PATCH 6/8] ENH: Add better header doc

---
 doc/advanced_configuration.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index 2c21623d9..b6e8b8dda 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -2,6 +2,13 @@
 Configuration
 =============
 
+Configuration and customization of sphinx-gallery is done primarily with a
+dictionary specified in your ``conf.py`` file. A list of the possible
+keys are listed :ref:`below <list_of_options>` and explained in
+greater detail in subsequent sections.
+
+.. _list_of_options:
+
 List of config options
 ======================
 

From 38e3cbabf8ccd60ed8a21e16894c9dc4435b9450 Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Tue, 1 Aug 2017 10:15:11 -0600
Subject: [PATCH 7/8] FIX: Add missing entry

---
 doc/advanced_configuration.rst | 15 +++++++++++++++
 doc/conf.py                    |  1 +
 2 files changed, 16 insertions(+)

diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index b6e8b8dda..f28f7cd2a 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -24,6 +24,7 @@ file:
 - ``line_numbers`` (:ref:`adding_line_numbers`)
 - ``download_section_examples`` (:ref:`disable_joint_download`)
 - ``plot_gallery`` (:ref:`without_execution`)
+- ``find_mayavi_figures`` (:ref:`find_mayavi`)
 - ``abort_on_example_error`` (:ref:`abort_on_first`)
 - ``expected_failing_examples`` (:ref:`dont_fail_exit`)
 
@@ -385,6 +386,20 @@ The highest precedence is always given to the `-D` flag of the
 ``sphinx-build`` command.
 
 
+.. _find_mayavi:
+
+Finding Mayavi figures
+======================
+By default, Sphinx-gallery will only look for :mod:`matplotlib` figures
+when building. However, extracting figures generated by :mod:`mayavi` is
+also supported. To enable this feature, you can do::
+
+
+    sphinx_gallery_conf = {
+        'find_mayavi_figures': True,
+    }
+
+
 Dealing with failing Gallery example scripts
 ============================================
 
diff --git a/doc/conf.py b/doc/conf.py
index 7b8c85fb0..8a39a0b95 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -298,6 +298,7 @@ def setup(app):
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
     'matplotlib': ('https://matplotlib.org/', None),
+    'mayavi': ('http://docs.enthought.com/mayavi/mayavi', None),
 }
 
 from sphinx_gallery.sorting import ExplicitOrder

From 6cc97180ed72bc690dea8cf169b9ce8230a22148 Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Tue, 1 Aug 2017 14:28:28 -0600
Subject: [PATCH 8/8] FIX: Fix links

---
 doc/advanced_configuration.rst | 8 ++++----
 doc/conf.py                    | 5 +++++
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/advanced_configuration.rst b/doc/advanced_configuration.rst
index f28f7cd2a..4a7d863f8 100644
--- a/doc/advanced_configuration.rst
+++ b/doc/advanced_configuration.rst
@@ -182,7 +182,7 @@ Adding references to examples
 
 Sphinx-Gallery enables you, when documenting your modules, to
 reference to the examples that use a particular function. For example
-if we are documenting the :data:`numpy.exp` function its possible to embed
+if we are documenting the :func:`numpy.exp` function its possible to embed
 a small gallery of examples that is specific to this function and
 looks like this:
 
@@ -390,8 +390,8 @@ The highest precedence is always given to the `-D` flag of the
 
 Finding Mayavi figures
 ======================
-By default, Sphinx-gallery will only look for :mod:`matplotlib` figures
-when building. However, extracting figures generated by :mod:`mayavi` is
+By default, Sphinx-gallery will only look for :mod:`matplotlib.pyplot` figures
+when building. However, extracting figures generated by :mod:`mayavi.mlab` is
 also supported. To enable this feature, you can do::
 
 
@@ -411,7 +411,7 @@ thumbnail. That allows you to find with a quick glance of the gallery
 which examples failed. Broken examples remain accessible in the html
 view of the gallery and the traceback message is written for the
 failing code block. Refer to example
-:ref:`sphx_glr_auto_examples_plot_raise.py` to view the default
+:ref:`sphx_glr_auto_examples_no_output_plot_raise.py` to view the default
 behavior.
 
 The build is also failed exiting with code 1 and giving you a summary
diff --git a/doc/conf.py b/doc/conf.py
index 8a39a0b95..eaa5dff23 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -84,6 +84,11 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
+# See warnings about bad links
+nitpicky = True
+# we intentionally link outside images
+suppress_warnings = ['image.nonlocal_uri']
+
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #default_role = None