Merge pull request #81 from SamWhited/issue61-better-docstrings

Improve docstring formatting

docs/source/conf.py

@@ -39,6 +39,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
     'alabaster',
 ]
 

libraw/bindings.py

@@ -163,8 +163,8 @@ def version_number(self):
 
             (0, 16, 1)
 
-        :returns: The version number
-        :rtype: :class:`3 tuple`
+        Returns:
+            3 tuple: The version number
         """
         v = self.libraw_versionNumber()
         return ((v >> 16) & 0x0000ff, (v >> 8) & 0x0000ff, v & 0x0000ff)
@@ -177,8 +177,8 @@ def version(self):
 
             "0.16.1-Release"
 
-        :returns: The version
-        :rtype: :class:`str`
+        Returns:
+            str: The version
         """
         return self.libraw_version().decode('utf-8')
 

libraw/callbacks.py

@@ -1,9 +1,11 @@
 """:mod:`libraw.callbacks` --- LibRaw callback definitions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Note that you will need to keep a reference to your callback functions for as
-long as you want to call them from C code, otherwise they may be garbage
-collected and lead to a segmentation fault.
+Warning:
+
+    You will need to keep a reference to your callback functions for as long as
+    you want to call them from C code, otherwise they may be garbage collected
+    and lead to a segmentation fault.
 """
 
 from ctypes import *  # noqa
@@ -31,10 +33,12 @@ def exif_cb(context, tag, type, len, ord, ifp):
         void *context, int tag, int type, int len, unsigned int ord, void *ifp
     );
 
-:param callback: the Python function to convert to a C callback.
-:type callback: :class:`function`
-:returns: A C callback
-:rtype: :class:`_ctypes.PyCFuncPtrType`
+
+Args:
+    callback (function): The Python function to convert to a C callback.
+
+Returns:
+    _ctypes.PyCFuncPtrType: A C callback.
 """
 
 memory_callback = CFUNCTYPE(c_void_p, c_char_p, c_char_p)
@@ -58,10 +62,11 @@ def memory_cb(data, file, where):
         void *data, const char *file, const char *where
     );
 
-:param callback: the Python function to convert to a C callback.
-:type callback: :class:`function`
-:returns: A C callback
-:rtype: :class:`_ctypes.PyCFuncPtrType`
+Args:
+    callback (function): The Python function to convert to a C callback.
+
+Returns:
+    _ctypes.PyCFuncPtrType: A C callback.
 """
 
 data_callback = CFUNCTYPE(c_void_p, c_char_p, c_int)
@@ -85,10 +90,11 @@ def data_cb(data, file, offset):
         void *data, const char *file, const int offset
     );
 
-:param callback: the Python function to convert to a C callback.
-:type callback: :class:`function`
-:returns: A C callback
-:rtype: :class:`_ctypes.PyCFuncPtrType`
+Args:
+    callback (function): The Python function to convert to a C callback.
+
+Returns:
+    _ctypes.PyCFuncPtrType: A C callback.
 """
 
 progress_callback = CFUNCTYPE(c_void_p, c_int, c_int, c_int)
@@ -112,8 +118,9 @@ def progress_cb(data, stage, iteration, expected):
         void *data, enum LibRaw_progress stage, int iterationa, int expected
     );
 
-:param callback: the Python function to convert to a C callback.
-:type callback: :class:`function`
-:returns: A C callback
-:rtype: :class:`_ctypes.PyCFuncPtrType`
+Args:
+    callback (function): The Python function to convert to a C callback.
+
+Returns:
+    _ctypes.PyCFuncPtrType: A C callback.
 """

libraw/errors.py

@@ -105,21 +105,23 @@ def check_call(exit_code, func, arguments):
     """
     Throws a Python error which corresponds to the given LibRaw exit code.
 
-    :param exit_code: the exit code returned by a LibRaw function
-    :type exit_code: :class:`int`
-    :raises: :exc:`~UnspecifiedError`
-             :exc:`~FileUnsupported`
-             :exc:`~FileUnsupported`
-             :exc:`~RequestForNonexistentImage`
-             :exc:`~OutOfOrderCall`
-             :exc:`~NoThumbnail`
-             :exc:`~UnsupportedThumbnail`
-             :exc:`~InputClosed`
-             :exc:`~InsufficientMemory`
-             :exc:`~DataError`
-             :exc:`~IOError`
-             :exc:`~CancelledByCallback`
-             :exc:`~BadCrop`
+    Args:
+        exit_code (int): An exit code returned by a LibRaw function.
+
+    Raises:
+        UnspecifiedError: We're not sure what happened.
+        FileUnsupported: The file is not a raw file that we recognize.
+        RequestForNonexistentImage: The given IFD does not contain an image.
+        OutOfOrderCall: Something was called out of order (eg. before data was
+                        unpacked)
+        NoThumbnail: The image does not have a thumbnail.
+        UnsupportedThumbnail: The embedded thumbnail format is unsupported.
+        InputClosed: The input stream has been closed.
+        InsufficientMemory: We're out of memory.
+        DataError: The unpacking step failed.
+        IOError: Reading was interrupted (or the file is corrupt).
+        CancelledByCallback: A callback canceled the operation.
+        BadCrop: The crop range was invalid.
     """
 
     if func.restype is c_error and exit_code.value != 0:

rawkit/errors.py

@@ -11,8 +11,7 @@ class InvalidFileType(ValueError):
 
     """
     Raised when an invalid file type or file extension is passed to a rawkit
-    method. If rawkit does not know what the filetype is, a
-    :exc:`libraw.errors.FileUnsupported` may be raised instead.
+    method.
     """
 
 

rawkit/options.py

@@ -174,16 +174,16 @@ class WhiteBalance(namedtuple('WhiteBalance',
     white balance multipliers stack (eg. you can use auto white balance, and
     then specify a manual ``rgbg`` multiplier on top of that).
 
-    :param auto: determines if we should automatically set the WB
-    :type auto: :class:`boolean`
-    :param camera: causes us to use the camera defined WB if present
-    :type camera: :class:`boolean`
-    :param greybox: set the WB based on a neutral grey region of the image
-    :type greybox: :class:`4 int tuple`
-    :param rgbg: set the WB manually based on an RGBG channel multiplier
-    :type rgbg: :class:`4 float tuple`
-    :returns: A white blance object
-    :rtype: :class:`WhiteBalance`
+    Args:
+        auto (boolean): Determines if we should automatically set the WB.
+        camera (boolean): Causes us to use the camera defined WB if present.
+        greybox (4 int tuple): Set the WB based on a neutral grey region of the
+                               image.
+        rgbg (4 float tuple): Set the WB manually based on an RGBG channel
+                              multiplier.
+
+    Returns:
+        WhiteBalance: A white balance object.
     """
 
     __slots__ = ()
@@ -198,9 +198,9 @@ class Options(object):
     """
     Represents a set of options which can be used when processing raw data.
 
-    :param attrs: a subscriptable object from which to take the initial state
-                  of the options object.
-    :type attrs: :class:`dict`
+    Args:
+        attrs (dict): A subscriptable object from which to take the initial
+                      state of the options object.
     """
 
     __slots__ = [
@@ -231,7 +231,6 @@ class Options(object):
         '_green_matching',
         '_bad_pixels_file',
     ]
-    """The options which are supported by this class."""
 
     def __init__(self, attrs=None):
         """
@@ -256,9 +255,7 @@ def __iter__(self):
                 raise StopIteration
 
     def __repr__(self):
-        """
-        Represents the options as a dict.
-        """
+        """Represents the options as a dict."""
         return repr(dict(self))
 
     def keys(self):
@@ -267,8 +264,8 @@ def keys(self):
         been set by the user (even if those options are set to the default
         value).
 
-        :returns: List of option keys which have been set
-        :rtype: :class:`tuple`
+        Returns:
+            tuple: List of option keys which have been set.
         """
         return [slot[1:] for slot in self.__slots__ if getattr(self, slot) is
                 not None]
@@ -277,14 +274,16 @@ def values(self):
         """
         The values of all options which appear in :func:`keys`.
 
-        :returns: List of options values
-        :rtype: :class:`tuple`
+        Returns:
+            tuple: List of options values.
         """
         return [self.__getitem__(k) for k in self.keys()]
 
     def __getitem__(self, k):
         """
-        Allow accessing options with dictionary syntax eg. opts['half_size'].
+        Allow accessing options with dictionary syntax eg. ::
+
+            opts['half_size'].
         """
         return getattr(self, k)
 
@@ -746,8 +745,9 @@ def _map_to_libraw_params(self, params):
         Internal method that writes rawkit options into the libraw options
         struct with the proper C data types.
 
-        :param params: the output params struct to set
-        :type params: :class:`libraw.structs.libraw_output_params_t`
+        Args:
+            params (libraw.structs.libraw_output_params_t):
+                The output params struct to set.
         """
         for slot in self.__slots__:
             prop = slot[1:]

rawkit/raw.py

@@ -31,11 +31,14 @@ class Raw(object):
             raw.options.white_balance = WhiteBalance(camera=False, auto=True)
             raw.save(filename='some/destination/image.ppm')
 
-    :param filename: the name of a raw file to load
-    :type filename: :class:`str`
-    :returns: A raw object
-    :rtype: :class:`Raw`
-    :raises: :exc:`rawkit.errors.NoFileSpecified`
+    Args:
+        filename (str): The name of a raw file to load.
+
+    Returns:
+        Raw: A raw object.
+
+    Raises:
+        rawkit.errors.NoFileSpecified: If `filename` is ``None``.
     """
 
     def __init__(self, filename=None):
@@ -84,12 +87,14 @@ def save(self, filename=None, filetype='ppm'):
         """
         Save the image data as a new PPM or TIFF image.
 
-        :param filename: the name of an image file to save
-        :type filename: :class:`str`
-        :param filetype: the type of file to output (``ppm`` or ``tiff``)
-        :type filetype: :class:`str`
-        :raises: :exc:`rawkit.errors.NoFileSpecified`
-                 :exc:`rawkit.errors.InvalidFileTypeError`
+        Args:
+            filename (str): The name of an image file to save.
+            filetype (str): The type of file to output (``ppm`` or ``tiff``).
+
+        Raises:
+            rawkit.errors.NoFileSpecified: If `filename` is ``None``.
+            rawkit.errors.InvalidFileTypeError: If `filetype` is not ``ppm`` or
+                ``tiff``.
         """
         if filename is None:
             raise NoFileSpecified()
@@ -107,20 +112,26 @@ def save_thumb(self, filename=None):
         """
         Save the thumbnail data.
 
-        :param filename: the name of an image file to save
-        :type filename: :class:`str`
+        Args:
+            filename (str): The name of an image file to save.
+
+        Raises:
+            rawkit.errors.NoFileSpecified: If `filename` is ``None``.
         """
+        if filename is None:
+            raise NoFileSpecified()
+
         self.unpack_thumb()
 
         self.libraw.libraw_dcraw_thumb_writer(
             self.data, filename.encode('ascii'))
 
     def to_buffer(self):
         """
-        Return the image data as an RGB buffer.
+        Convert the image to an RGB buffer.
 
-        :returns: RGB data of the image
-        :rtype: :class:`bytearray`
+        Returns:
+            bytearray: RGB data of the image.
         """
         self.unpack()
         self.process()
@@ -137,10 +148,10 @@ def to_buffer(self):
 
     def thumbnail_to_buffer(self):
         """
-        Return the thumbnail data as an RGB buffer.
+        Convert the thumbnail data as an RGB buffer.
 
-        :returns: RGB data of the thumbnail
-        :rtype: :class:`bytearray`
+        Returns:
+            bytearray: RGB data of the thumbnail.
         """
         self.unpack_thumb()
 
@@ -159,8 +170,8 @@ def metadata(self):
         """
         Common metadata for the photo
 
-        :returns: A metadata object
-        :rtype: :class:`~rawkit.metadata.Metadata`
+        Returns:
+            rawkit.metadata.Metadata: A metadata object.
         """
         return Metadata(
             aperture=self.data.contents.other.aperture,
@@ -185,8 +196,6 @@ class DarkFrame(Raw):
 
     Creates a temporary file which is not cleaned up until the dark frame is
     closed.
-
-    :See also: :class:`rawkit.raw.Raw`
     """
 
     def __init__(self, filename=None):
@@ -215,11 +224,13 @@ def save(self, filename=None, filetype='ppm'):
         """
         Save the image data, defaults to using a temp file.
 
-        :param filename: the name of an image file to save
-        :type filename: :class:`str`
-        :param filetype: the type of file to output (``ppm`` or ``tiff``)
-        :type filetype: :class:`str`
-        :raises: :exc:`rawkit.errors.InvalidFileTypeError`
+        Args:
+            filename (str): The name of an image file to save.
+            filetype (str): The type of file to output (``ppm`` or ``tiff``).
+
+        Raises:
+            rawkit.errors.InvalidFileTypeError: If `filetype` is not ``ppm`` or
+                ``tiff``.
         """
 
         if filename is None:
@@ -233,8 +244,8 @@ def name(self):
         """
         A tempfile in a unique directory.
 
-        :returns: The name of a temp file
-        :rtype: :class:`str`
+        Returns:
+            str: The name of a temp file.
         """
         return self._tmp