Merge pull request scikit-learn#4658 from Titan-C/sphx-glr

[MRG+2] Sphinx-gallery use

Author: GaelVaroquaux

doc/conf.py

@@ -24,24 +24,18 @@
 sys.path.insert(0, os.path.abspath('sphinxext'))
 
 from github_link import make_linkcode_resolve
+import sphinx_gallery
 
 # -- General configuration ---------------------------------------------------
 
-# Try to override the matplotlib configuration as early as possible
-try:
-    import gen_rst
-except:
-    pass
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['gen_rst',
-              'sphinx.ext.autodoc', 'sphinx.ext.autosummary',
-              'sphinx.ext.pngmath', 'numpy_ext.numpydoc',
-              'sphinx.ext.linkcode', 'sphinx.ext.doctest',
-              ]
-
-autosummary_generate = True
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.autosummary',
+    'sphinx.ext.pngmath', 'numpy_ext.numpydoc',
+    'sphinx.ext.linkcode', 'sphinx.ext.doctest',
+    'sphinx_gallery.gen_gallery',
+]
 
 autodoc_default_flags = ['members', 'inherited-members']
 
@@ -230,20 +224,46 @@
 trim_doctests_flags = True
 
 
-def generate_example_rst(app, what, name, obj, options, lines):
-    # generate empty examples files, so that we don't get
-    # inclusion errors if there are no examples for a class / module
-    examples_path = os.path.join(app.srcdir, "modules", "generated",
-                                 "%s.examples" % name)
-    if not os.path.exists(examples_path):
-        # touch file
-        open(examples_path, 'w').close()
+sphinx_gallery_conf = {
+    'doc_module': 'sklearn',
+    'reference_url': {
+        'sklearn': None,
+        'matplotlib': 'http://matplotlib.org',
+        'numpy': 'http://docs.scipy.org/doc/numpy-1.6.0',
+        'scipy': 'http://docs.scipy.org/doc/scipy-0.11.0/reference',
+        'nibabel': 'http://nipy.org/nibabel'}
+}
+
+
+# The following dictionary contains the information used to create the
+# thumbnails for the front page of the scikit-learn home page.
+# key: first image in set
+# values: (number of plot in set, height of thumbnail)
+carousel_thumbs = {'sphx_glr_plot_classifier_comparison_001.png': 600,
+                   'sphx_glr_plot_outlier_detection_003.png': 372,
+                   'sphx_glr_plot_gpr_co2_001.png': 350,
+                   'sphx_glr_plot_adaboost_twoclass_001.png': 372,
+                   'sphx_glr_plot_compare_methods_001.png': 349}
+
+
+def make_carousel_thumbs(app, exception):
+    """produces the final resized carousel images"""
+    if exception is not None:
+        return
+    print('Preparing carousel images')
+
+    image_dir = os.path.join(app.builder.outdir, '_images')
+    for glr_plot, max_width in carousel_thumbs.items():
+        image = os.path.join(image_dir, glr_plot)
+        if os.path.exists(image):
+            c_thumb = os.path.join(image_dir, glr_plot[:-4] + '_carousel.png')
+            sphinx_gallery.gen_rst.scale_image(image, c_thumb, max_width, 190)
 
 
 def setup(app):
     # to hide/show the prompt in code examples:
     app.add_javascript('js/copybutton.js')
-    app.connect('autodoc-process-docstring', generate_example_rst)
+    app.connect('build-finished', make_carousel_thumbs)
 
 
 # The following is used by sphinx.ext.linkcode to provide links to github

doc/datasets/index.rst

@@ -82,7 +82,7 @@ and pipeline on 2D data.
    load_sample_images
    load_sample_image
 
-.. image:: ../auto_examples/cluster/images/plot_color_quantization_001.png
+.. image:: ../auto_examples/cluster/images/sphx_glr_plot_color_quantization_001.png
    :target: ../auto_examples/cluster/plot_color_quantization.html
    :scale: 30
    :align: right
@@ -98,7 +98,7 @@ and pipeline on 2D data.
 
 .. topic:: Examples:
 
-    * :ref:`example_cluster_plot_color_quantization.py`
+    * :ref:`sphx_glr_auto_examples_cluster_plot_color_quantization.py`
 
 
 .. _sample_generators:
@@ -130,7 +130,7 @@ per class; and linear transformations of the feature space.
 near-equal-size classes separated by concentric hyperspheres.
 :func:`make_hastie_10_2` generates a similar binary, 10-dimensional problem.
 
-.. image:: ../auto_examples/datasets/images/plot_random_dataset_001.png
+.. image:: ../auto_examples/datasets/images/sphx_glr_plot_random_dataset_001.png
    :target: ../auto_examples/datasets/plot_random_dataset.html
    :scale: 50
    :align: center
@@ -159,7 +159,7 @@ respect to true bag-of-words mixtures include:
 * Documents without labels words at random, rather than from a base
   distribution.
 
-.. image:: ../auto_examples/datasets/images/plot_random_multilabel_dataset_001.png
+.. image:: ../auto_examples/datasets/images/sphx_glr_plot_random_multilabel_dataset_001.png
    :target: ../auto_examples/datasets/plot_random_multilabel_dataset.html
    :scale: 50
    :align: center

doc/datasets/labeled_faces.rst

@@ -115,4 +115,4 @@ an evaluation ``10_folds`` set meant to compute performance metrics using a
 Examples
 --------
 
-:ref:`example_applications_face_recognition.py`
+:ref:`sphx_glr_auto_examples_applications_face_recognition.py`

doc/datasets/twenty_newsgroups.rst

@@ -135,7 +135,7 @@ which is fast to train and achieves a decent F-score::
   >>> metrics.f1_score(newsgroups_test.target, pred, average='macro')
   0.88213592402729568
 
-(The example :ref:`example_text_document_classification_20newsgroups.py` shuffles
+(The example :ref:`sphx_glr_auto_examples_text_document_classification_20newsgroups.py` shuffles
 the training and test data, instead of segmenting by time, and in that case
 multinomial Naive Bayes gets a much higher F-score of 0.88. Are you suspicious
 yet of what's going on inside this classifier?)
@@ -201,7 +201,7 @@ It loses even more if we also strip this metadata from the training data:
   0.76995175184521725
 
 Some other classifiers cope better with this harder version of the task. Try
-running :ref:`example_model_selection_grid_search_text_feature_extraction.py` with and without
+running :ref:`sphx_glr_auto_examples_model_selection_grid_search_text_feature_extraction.py` with and without
 the ``--filter`` option to compare the results.
 
 .. topic:: Recommendation
@@ -213,6 +213,6 @@ the ``--filter`` option to compare the results.
 
 .. topic:: Examples
 
-   * :ref:`example_model_selection_grid_search_text_feature_extraction.py`
+   * :ref:`sphx_glr_auto_examples_model_selection_grid_search_text_feature_extraction.py`
 
-   * :ref:`example_text_document_classification_20newsgroups.py`
+   * :ref:`sphx_glr_auto_examples_text_document_classification_20newsgroups.py`

doc/developers/performance.rst

@@ -127,7 +127,7 @@ for interactively exploring the relevant part for the code.
 
 Suppose we want to profile the Non Negative Matrix Factorization module
 of the scikit. Let us setup a new IPython session and load the digits
-dataset and as in the :ref:`example_classification_plot_digits_classification.py` example::
+dataset and as in the :ref:`sphx_glr_auto_examples_classification_plot_digits_classification.py` example::
 
   In [1]: from sklearn.decomposition import NMF
 

doc/modules/biclustering.rst

@@ -44,8 +44,8 @@ biclusters on the diagonal. Here is an example of this structure
 where biclusters have higher average values than the other rows and
 columns:
 
-.. figure:: ../auto_examples/bicluster/images/plot_spectral_coclustering_003.png
-   :target: ../auto_examples/bicluster/images/plot_spectral_coclustering_003.png
+.. figure:: ../auto_examples/bicluster/images/sphx_glr_plot_spectral_coclustering_003.png
+   :target: ../auto_examples/bicluster/images/sphx_glr_plot_spectral_coclustering_003.png
    :align: center
    :scale: 50
 
@@ -56,8 +56,8 @@ each column belongs to all row clusters. Here is an example of this
 structure where the variance of the values within each bicluster is
 small:
 
-.. figure:: ../auto_examples/bicluster/images/plot_spectral_biclustering_003.png
-   :target: ../auto_examples/bicluster/images/plot_spectral_biclustering_003.png
+.. figure:: ../auto_examples/bicluster/images/sphx_glr_plot_spectral_biclustering_003.png
+   :target: ../auto_examples/bicluster/images/sphx_glr_plot_spectral_biclustering_003.png
    :align: center
    :scale: 50
 
@@ -150,11 +150,11 @@ and the remaining ``n_columns`` labels provide the column partitioning.
 
 .. topic:: Examples:
 
- * :ref:`example_bicluster_plot_spectral_coclustering.py`: A simple example
+ * :ref:`sphx_glr_auto_examples_bicluster_plot_spectral_coclustering.py`: A simple example
    showing how to generate a data matrix with biclusters and apply
    this method to it.
 
- * :ref:`example_bicluster_bicluster_newsgroups.py`: An example of finding
+ * :ref:`sphx_glr_auto_examples_bicluster_bicluster_newsgroups.py`: An example of finding
    biclusters in the twenty newsgroup dataset.
 
 
@@ -237,7 +237,7 @@ clustering this :math:`n \times q` matrix yields the column labels.
 
 .. topic:: Examples:
 
- * :ref:`example_bicluster_plot_spectral_biclustering.py`: a simple example
+ * :ref:`sphx_glr_auto_examples_bicluster_plot_spectral_biclustering.py`: a simple example
    showing how to generate a checkerboard matrix and bicluster it.
 
 

doc/modules/calibration.rst

@@ -22,7 +22,7 @@ such that among the samples to which it gave a predict_proba value close to 0.8,
 approximately 80% actually belong to the positive class. The following plot compares
 how well the probabilistic predictions of different classifiers are calibrated:
 
-.. figure:: ../auto_examples/calibration/images/plot_compare_calibration_001.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_compare_calibration_001.png
    :target: ../auto_examples/calibration/plot_compare_calibration.html
    :align: center
 
@@ -87,7 +87,7 @@ The first image present a dataset with 2 classes and 3 blobs of
 data. The blob in the middle contains random samples of each class.
 The probability for the samples in this blob should be 0.5.
 
-.. figure:: ../auto_examples/calibration/images/plot_calibration_001.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_calibration_001.png
    :target: ../auto_examples/calibration/plot_calibration.html
    :align: center
 
@@ -98,7 +98,7 @@ calibration. One can observe that the non-parametric model
 provides the most accurate probability estimates for samples
 in the middle, i.e., 0.5.
 
-.. figure:: ../auto_examples/calibration/images/plot_calibration_002.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_calibration_002.png
    :target: ../auto_examples/calibration/plot_calibration.html
    :align: center
 
@@ -113,7 +113,7 @@ both isotonic calibration and sigmoid calibration. The calibration performance
 is evaluated with Brier score :func:`brier_score_loss`, reported in the legend
 (the smaller the better).
 
-.. figure:: ../auto_examples/calibration/images/plot_calibration_curve_002.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_calibration_curve_002.png
    :target: ../auto_examples/calibration/plot_calibration_curve.html
    :align: center
 
@@ -126,7 +126,7 @@ kinds of calibration can fix this issue and yield nearly identical results.
 The next figure shows the calibration curve of Gaussian naive Bayes on
 the same data, with both kinds of calibration and also without calibration.
 
-.. figure:: ../auto_examples/calibration/images/plot_calibration_curve_001.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_calibration_curve_001.png
    :target: ../auto_examples/calibration/plot_calibration_curve.html
    :align: center
 
@@ -167,7 +167,7 @@ probability vectors predicted by the same classifier after sigmoid calibration
 on a hold-out validation set. Colors indicate the true class of an instance
 (red: class 1, green: class 2, blue: class 3).
 
-.. figure:: ../auto_examples/calibration/images/plot_calibration_multiclass_000.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_calibration_multiclass_000.png
    :target: ../auto_examples/calibration/plot_calibration_multiclass.html
    :align: center
 
@@ -179,7 +179,7 @@ method='sigmoid' on the remaining 200 datapoints reduces the confidence of the
 predictions, i.e., moves the probability vectors from the edges of the simplex
 towards the center:
 
-.. figure:: ../auto_examples/calibration/images/plot_calibration_multiclass_001.png
+.. figure:: ../auto_examples/calibration/images/sphx_glr_plot_calibration_multiclass_001.png
    :target: ../auto_examples/calibration/plot_calibration_multiclass.html
    :align: center