Merge pull request #1295 from stefanv/doc_build_fixes

Doc build fixes

doc/examples/plot_label.py

@@ -19,7 +19,8 @@ import matplotlib.patches as mpatches
 from skimage import data
 from skimage.filters import threshold_otsu
 from skimage.segmentation import clear_border
-from skimage.morphology import label, closing, square
+from skimage.measure import label
+from skimage.morphology import closing, square
 from skimage.measure import regionprops
 from skimage.color import label2rgb
 

doc/examples/plot_regionprops.py

@@ -11,8 +11,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 from skimage.draw import ellipse
-from skimage.morphology import label
-from skimage.measure import regionprops
+from skimage.measure import label, regionprops
 from skimage.transform import rotate
 
 

doc/examples/plot_tinting_grayscale_images.py

@@ -37,7 +37,7 @@ ax2.imshow(yellow_multiplier * image)
 
 In many cases, dealing with RGB values may not be ideal. Because of that, there
 are many other `color spaces`_ in which you can represent a color image. One
-popular color space is called HSV_, which represents hue (~the color),
+popular color space is called HSV, which represents hue (~the color),
 saturation (~colorfulness), and value (~brightness). For example, a color
 (hue) might be green, but its saturation is how intense that green is---where
 olive is on the low end and neon on the high end.
@@ -46,6 +46,9 @@ In some implementations, the hue in HSV goes from 0 to 360, since hues wrap
 around in a circle. In scikit-image, however, hues are float values from 0 to
 1, so that hue, saturation, and value all share the same scale.
 
+.. _color spaces:
+    http://en.wikipedia.org/wiki/List_of_color_spaces_and_their_uses
+
 Below, we plot a linear gradient in the hue, with the saturation and value
 turned all the way up:
 """
@@ -69,6 +72,8 @@ Notice how the colors at the far left and far right are the same. That reflects
 the fact that the hues wrap around like the color wheel (see HSV_ for more
 info).
 
+.. _HSV: http://en.wikipedia.org/wiki/HSL_and_HSV
+
 Now, let's create a little utility function to take an RGB image and:
 
 1. Transform the RGB image to HSV
@@ -147,7 +152,4 @@ plt.show()
 For coloring multiple regions, you may also be interested in
 `skimage.color.label2rgb <http://scikit-image.org/docs/0.9.x/api/skimage.color.html#label2rgb>`_.
 
-.. _color spaces:
-    http://en.wikipedia.org/wiki/List_of_color_spaces_and_their_uses
-.. _HSV: http://en.wikipedia.org/wiki/HSL_and_HSV
 """

doc/examples/plot_windowed_histogram.py

@@ -60,10 +60,12 @@ def windowed_histogram_similarity(image, selem, reference_hist, n_bins):
     # a measure of distance between histograms
     X = px_histograms
     Y = reference_hist
+
     num = (X - Y) ** 2
     denom = X + Y
+    denom[denom == 0] = np.infty
     frac = num / denom
-    frac[denom == 0] = 0
+
     chi_sqr = 0.5 * np.sum(frac, axis=2)
 
     # Generate a similarity measure. It needs to be low when distance is high

doc/ext/plot2rst.py

@@ -66,10 +66,12 @@ Suggested CSS definitions
 
 """
 import os
+import re
 import shutil
 import token
 import tokenize
 import traceback
+import itertools
 
 import numpy as np
 import matplotlib
@@ -83,7 +85,7 @@ from skimage.util.dtype import dtype_range
 from notebook import Notebook
 
 from docutils.core import publish_parts
-
+from sphinx.domains.python import PythonDomain
 
 LITERALINCLUDE = """
 .. literalinclude:: {src_name}
@@ -332,6 +334,8 @@ def write_example(src_name, src_dir, rst_dir, cfg):
         notebook_path.exists:
         return
 
+    print('plot2rst: %s' % basename)
+
     blocks = split_code_and_text_blocks(example_file)
     if blocks[0][2].startswith('#!'):
         blocks.pop(0) # don't add shebang line to rst file.
@@ -380,15 +384,57 @@ def write_example(src_name, src_dir, rst_dir, cfg):
     # Export example to IPython notebook
     nb = Notebook()
 
-    for (cell_type, _, content) in blocks:
-        content = content.rstrip('\n')
+    # Add sphinx roles to the examples, otherwise docutils
+    # cannot compile the ReST for the notebook
+    sphinx_roles = PythonDomain.roles.keys()
+    preamble = '\n'.join('.. role:: py:{0}(literal)\n'.format(role)
+                         for role in sphinx_roles)
 
+    # Grab all references to inject them in cells where needed
+    ref_regexp = re.compile('\n(\.\. \[(\d+)\].*(?:\n[ ]{7,8}.*)+)')
+    math_role_regexp = re.compile(':math:`(.*?)`')
+
+    text = '\n'.join((content for (cell_type, _, content) in blocks
+                     if cell_type != 'code'))
+
+    references = re.findall(ref_regexp, text)
+
+    for (cell_type, _, content) in blocks:
         if cell_type == 'code':
             nb.add_cell(content, cell_type='code')
         else:
-            content = content.replace('"""', '')
+            if content.startswith('r'):
+                content = content.replace('r"""', '')
+                escaped = False
+            else:
+                content = content.replace('"""', '')
+                escaped = True
+
+            if not escaped:
+                content = content.replace("\\", "\\\\")
+
+            content = content.replace('.. seealso::', '**See also:**')
+            content = re.sub(math_role_regexp, r'$\1$', content)
+
+            # Remove math directive when rendering notebooks
+            # until we implement a smarter way of capturing and replacing
+            # its content
+            content = content.replace('.. math::', '')
+
+            if not content.strip():
+                continue
+
+            content = (preamble + content).rstrip('\n')
             content = '\n'.join([line for line in content.split('\n') if
                                  not line.startswith('.. image')])
+
+            # Remove reference links until we can figure out a better way to
+            # preserve them
+            for (reference, ref_id) in references:
+                ref_tag = '[{0}]_'.format(ref_id)
+                if ref_tag in content:
+                    content = content.replace(ref_tag, ref_tag[:-1])
+
             html = publish_parts(content, writer_name='html')['html_body']
             nb.add_cell(html, cell_type='markdown')