Repository: wright-group/WrightTools

Issue:
Links in docstrings
I prefer the rST link format where the links are separated from the hyperlink text

This makes lines shorter (silencing flake8 warnings often, unless urls are particularly long)
And also makes it (in my opinion) easier to read, as the urls clog up the view when most of the time I am not interested in them unless I am explicitly looking for the link.

For short urls, it is still appropriate to have it in line, as those are not too distracting, and can be useful

The link url is available, and the syntax is such that it is clear a link is indicated, and the URL should be relatively close by.


Discussion:
I agree, and move that we bring all links to the bottom of the docstring.

@ksunden can you just go through and do this all at once?
Note the rST format  requires the links to be in the same block, so I am putting them closer to the actual reference to that link

Resolving patch:
diff --git a/WrightTools/artists.py b/WrightTools/artists.py
--- a/WrightTools/artists.py
+++ b/WrightTools/artists.py
@@ -1,4 +1,10 @@
 """ Tools for visualizing data.
+
+.. _gridspec: http://matplotlib.org/users/gridspec.html#gridspec-and-subplotspec
+.. _grayify: https://jakevdp.github.io/blog/2014/10/16/how-bad-is-your-colormap/
+.. _cubehelix: http://arxiv.org/abs/1108.5083.
+.. _colormap: http://nbviewer.ipython.org/gist/anonymous/a4fa0adb08f9e9ea4f94
+.. _nmtorgb: http://www.physics.sfasu.edu/astro/color/spectra.html
 """
 
 
@@ -33,7 +39,7 @@
 # string types
 if sys.version[0] == '2':
     # recognize unicode and string types
-    string_type = basestring  # noqa: F821 
+    string_type = basestring  # noqa: F821
 else:
     string_type = str  # newer versions of python don't have unicode type
 
@@ -524,8 +530,8 @@ def create_figure(width='single', nrows=1, cols=[1], margin=1.,
         contains SubplotSpec objects that can have axes placed into them.
         The SubplotSpec objects can be accessed through indexing: [row, col].
         Slicing works, for example ``cax = plt.subplot(gs[:, -1])``. See
-        `matplotlib documentation <http://matplotlib.org/1.4.0/users/gridspec.html#gridspec-and-subplotspec>`_
-        for more information.
+        matplotlib gridspec_ documentation for more information.
+
 
     Notes
     -----
@@ -542,6 +548,7 @@ def create_figure(width='single', nrows=1, cols=[1], margin=1.,
         debug and design purposes.
     wt.artsits.subplots_adjust
         Enforce margins for figure generated elsewhere.
+
     """
     # get width
     if width == 'double':
@@ -718,7 +725,10 @@ def get_scaled_bounds(ax, position, distance=0.1, factor=200):
 
 def grayify_cmap(cmap):
     """Return a grayscale version of the colormap
-    Source: https://jakevdp.github.io/blog/2014/10/16/how-bad-is-your-colormap/
+
+    `Source`__
+
+     __ grayify_
     """
     cmap = plt.cm.get_cmap(cmap)
     colors = cmap(np.arange(cmap.N))
@@ -731,7 +741,12 @@ def grayify_cmap(cmap):
 
 
 def make_cubehelix(gamma=0.5, s=0.25, r=-1, h=1.3, reverse=False, darkest=0.7):
-    """ Define cubehelix type colorbars. For more information see http://arxiv.org/abs/1108.5083.
+    """ Define cubehelix type colorbars.
+
+    Look `here`__ for more information.
+
+    __ cubehelix_
+
 
     Parameters
     ----------
@@ -789,7 +804,11 @@ def make_colormap(seq, name='CustomMap', plot=False):
 
     seq: a sequence of floats and RGB-tuples. The floats should be increasing
     and in the interval (0,1).
-    from http://nbviewer.ipython.org/gist/anonymous/a4fa0adb08f9e9ea4f94
+
+    `Source`__
+
+    __ colormap_
+
     """
     seq = [(None,) * 3, 0.0] + list(seq) + [1.0, (None,) * 3]
     cdict = {'red': [], 'green': [], 'blue': []}
@@ -809,7 +828,10 @@ def make_colormap(seq, name='CustomMap', plot=False):
 def nm_to_rgb(nm):
     """ returns list [r, g, b] (zero to one scale) for given input in nm
 
-    original code - http://www.physics.sfasu.edu/astro/color/spectra.html
+    `original code`__
+
+    __ nmtorgb_
+
     """
     w = int(nm)
     # color ---------------------------------------------------------------------------------------
@@ -1499,7 +1521,7 @@ def plot(self, channel=0, local=False, autosave=False, output_folder=None,
         if len(self.chopped) > 10:
             if not autosave:
                 print('too many images will be generated ({}): forcing autosave'.format(
-                                                          len(self.chopped)))
+                    len(self.chopped)))
                 autosave = True
         # prepare output folders
         if autosave:
diff --git a/WrightTools/data.py b/WrightTools/data.py
--- a/WrightTools/data.py
+++ b/WrightTools/data.py
@@ -922,8 +922,10 @@ def heal(self, channel=0, method='linear', fill_value=np.nan,
             Channel to heal. Default is 0.
         method : {'linear', 'nearest', 'cubic'} (optional)
             The interpolation method. Note that cubic interpolation is only
-            possible for 1D and 2D data. See `griddata <http://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.griddata.html>`_
-            for more information. Default is linear.
+            possible for 1D and 2D data. See `griddata`_ for more information.
+            Default is linear.
+
+            .. _griddata: http://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.griddata.html
         fill_value : number-like (optional)
             The value written to pixels that cannot be filled by interpolation.
             Default is nan.
@@ -1263,8 +1265,8 @@ def offset(self, points, offsets, along, offset_axis,
             interpolation range will be written nan.
         method : {'linear', 'nearest', 'cubic'} (optional)
             The interpolation method. Note that cubic interpolation is only
-            possible for 1D and 2D data. See `griddata <http://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.griddata.html>`_
-            for more information. Default is linear.
+            possible for 1D and 2D data. See `griddata`_ for more information.
+            Default is linear.
         verbose : bool (optional)
             Toggle talkback. Default is True.
 
@@ -1418,8 +1420,9 @@ def revert(self):
 
     def save(self, filepath=None, verbose=True):
         """
-        Save using the `pickle <https://docs.python.org/2/library/pickle.html>`_
-        module.
+        Save using the `pickle`_ module.
+
+        .. _pickle: https://docs.python.org/3/library/pickle.html
 
         Parameters
         ----------
@@ -1502,7 +1505,9 @@ def share_nans(self):
 
     def smooth(self, factors, channel=None, verbose=True):
         """
-        Smooth a channel using an n-dimenional `kaiser window <https://en.wikipedia.org/wiki/Kaiser_window>`_.
+        Smooth a channel using an n-dimenional `kaiser window`_.
+
+        .. _kaiser window: https://en.wikipedia.org/wiki/Kaiser_window
 
         Parameters
         ----------
@@ -1811,8 +1816,9 @@ def zoom(self, factor, order=1, verbose=True):
         """ Zoom the data array using spline interpolation of the requested order.
 
         The number of points along each axis is increased by factor.
-        See `scipy.ndimage.interpolation.zoom <http://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.interpolation.zoom.html>`_
-        for more info.
+        See `scipy ndimage`_ for more info.
+
+        .. _scipy ndimage: http://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.interpolation.zoom.html
 
         Parameters
         ----------
diff --git a/WrightTools/kit.py b/WrightTools/kit.py
--- a/WrightTools/kit.py
+++ b/WrightTools/kit.py
@@ -174,11 +174,15 @@ def __init__(self, at=None, timezone='local'):
         legacy : string
             Legacy WrightTools timestamp representation.
         RFC3339 : string
-            `RFC3339 <https://www.ietf.org/rfc/rfc3339.txt>`_ representation (recommended for most applications).
+            `RFC3339`_ representation (recommended for most applications).
         RFC5322 : string
-            `RFC5322 <https://tools.ietf.org/html/rfc5322#section-3.3>`_ representation.
+            `RFC5322`_ representation.
         path : string
             Representation of the timestamp meant for inclusion in filepaths.
+
+
+        .. _RFC3339: https://www.ietf.org/rfc/rfc3339.txt
+        .. _RFC5322: https://tools.ietf.org/html/rfc5322#section-3.3
         """
         # get timezone
         if timezone == 'local':
@@ -593,7 +597,9 @@ def read_data_column(path, name):
 
 
 def read_h5(filepath):
-    """ Read from a `HDF5 <https://www.hdfgroup.org/HDF5/doc/H5.intro.html>`_ file, returning the data within as a python dictionary.
+    """ Read from a `HDF5`_ file, returning the data within as a python dictionary.
+
+    .. _HDF5: https://www.hdfgroup.org/HDF5/doc/H5.intro.html
 
     Returns
     -------
@@ -603,6 +609,7 @@ def read_h5(filepath):
     See Also
     --------
     kit.write_h5
+
     """
     d = collections.OrderedDict()
     h5f = h5py.File(filepath, mode='r')
@@ -637,7 +644,7 @@ def read_headers(filepath):
 
 
 def write_h5(filepath, dictionary):
-    """ Save a python dictionary into an `HDF5 <https://www.hdfgroup.org/HDF5/doc/H5.intro.html>`_
+    """ Save a python dictionary into an `HDF5`_
     file.
 
     Right now it only works to store numpy arrays of numbers.


Test patch: