docs: add autodoc for formats and minor cleanup

docs/conf.py

@@ -74,6 +74,7 @@
               'sphinx.ext.napoleon',
               'sphinxcontrib.bibtex',
               'fancy_include',
+              'qpformat_readers',
               ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/extensions/qpformat_readers.py

@@ -0,0 +1,80 @@
+"""visualization of dclab definitions
+
+Usage
+-----
+Directives:
+
+Run autodoc on all supported formats:
+
+   .. autodoc_qpformats::
+
+Create table of all supported formats
+
+   .. qpformats::
+"""
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import Directive
+from sphinx.util.nodes import nested_parse_with_titles
+from docutils import nodes
+
+from qpformat.file_formats import formats_dict
+
+
+class Base(Directive):
+    required_arguments = 0
+    optional_arguments = 0
+
+    def generate_rst(self):
+        pass        
+
+    def run(self):
+        rst = self.generate_rst()
+
+        vl = ViewList(rst, "fakefile.rst")
+        # Create a node.
+        node = nodes.section()
+        node.document = self.state.document
+        # Parse the rst.
+        nested_parse_with_titles(self.state, vl, node)
+        return node.children
+
+
+class AutodocFormats(Base):
+    def generate_rst(self):
+        rst = []
+
+        for key in sorted(formats_dict.keys()):
+            rst.append("")
+            rst.append(".. autoclass:: qpformat.file_formats.{}".format(key))
+            rst.append("")
+
+        return rst
+
+
+class Formats(Base):
+    def generate_rst(self):
+        rst = []
+
+        rst.append(".. csv-table::")
+        rst.append("    :header: Class, Data type, Description".format())
+        rst.append("    :widths: 2, 2, 6")
+        rst.append("    :delim: tab")
+        rst.append("")
+
+        for key in sorted(formats_dict.keys()):
+            cl = formats_dict[key]
+            datatype = cl.storage_type
+            if not isinstance(datatype, str):
+                datatype = "multiple"
+            rst.append("    :class:`{key}<qpformat.file_formats.{key}>`\t {type}\t {doc}".format(
+                key=key, type=datatype, doc=cl.__doc__.split("\n", 1)[0]))
+
+        rst.append("")
+
+        return rst
+
+
+def setup(app):
+    app.add_directive('autodoc_qpformats', AutodocFormats)
+    app.add_directive('qpformats', Formats)
+    return {'version': '0.1'}   # identifies the version of our extension

docs/sec_code_reference.rst

@@ -5,3 +5,32 @@ Code reference
 .. toctree::
   :maxdepth: 2
 
+
+module-level
+============
+.. autofunction:: qpformat.load_data
+
+
+file format base classes
+========================
+SingleData
+----------
+.. autoclass:: qpformat.file_formats.dataset.SingleData
+    :inherited-members:
+
+SeriesData
+----------
+.. autoclass:: qpformat.file_formats.dataset.SeriesData
+    :members:
+
+
+file format readers
+===================
+.. autodoc_qpformats::
+
+
+exceptions
+==========
+.. autoexception:: qpformat.file_formats.MultipleFormatsNotSupportedError
+
+.. autoexception:: qpformat.file_formats.UnknownFileFormatError

docs/sec_introduction.rst

@@ -6,10 +6,21 @@ Introduction
   :maxdepth: 2
 
 
-Phase image retrieval
-=====================
-
-
 Why qpformat?
 =============
+There is a multitude of phase-imaging techniques that inevitably comes
+with a broad range of quantitative phase imaging (QPI) file formats.
+In addition, raw data, such as digital holographic microscopy (DHM) images,
+must be preprocessed to access the phase encoded in the interference pattern. 
+Qpformat provides a unified and user-friendly interface for loading QPI data.
+It is based on the :ref:`qpimage <qpimage:index>` library and thus benefits
+from its hdf5-based data structure (e.g. elaborate background correction,
+meta data management, and transparent data storage). Furthermore, qpformat
+can manage large datasets (e.g. many holograms in one folder) without running
+out of memory by means of its lazily-evaluated
+:class:`SeriesData <qpformat.file_formats.SeriesData` class.
+
+Supported file formats
+======================
+.. qpformats::
 

docs/userapi.rst

@@ -14,29 +14,23 @@ is that experimental data is not loaded into memory until the
 
 Basic Usage
 -----------
-The file format type is determined automatically by qpformat.
-If the file format is implemented in qpformat, experimental
-data can be loaded with the :py:func:`qpformat.load_data` method.
+To extract the (unwrapped) phase from a DHM image, use the
+:func:`qpformat.load_data` method. The file format type is
+determined automatically by qpformat.
 
-.. code-block:: python
+.. code:: python
 
-   # Obtain a qpformat.file_formats.SingleData object
-   # (the data is not loaded into memory, only the meta data is read)
-   ds = qpformat.load_data(path="/path/to/SID PHA_xxx.tif")
-   # Get the quantitative phase data (a qpimage.QPImage is returned)
-   qpi = ds.get_qpimage()
+    import qpformat
+    # The data are not loaded into memory, only the meta data is read
+    dataset = qpformat.load_data("/path/to/hologram_image.tif")
+    # Get the quantitative phase data (a qpimage.QPImage is returned)
+    qpi = dataset.get_qpimage()
+    # Get the 2D phase image data as a numpy array
+    phase = qpi.pha
 
-
-SingleData
-----------
-.. autoclass:: qpformat.file_formats.SeriesData
-    :inherited-members:
-
-SeriesData
-----------
-.. autoclass:: qpformat.file_formats.SeriesData
-    :members:
-
-Constants
----------
-.. autodata:: qpformat.file_formats.formats
+The object ``qpi`` is an instance of
+:class:`qpimage.QPImage <qpimage.core.QPImage>` which
+comes with an elaborate set of background correction methods. Note
+that :func:`qpformat.load_data` accepts keyword arguments that allow
+to define the setup metadata as well as the hologram reconstruction
+parameters.

examples/convert_txt2npy.py

@@ -3,7 +3,7 @@
 Sometimes the data recorded are not in a file format supported
 by qpformat or it is not feasible to implement a reader
 class for a very unique data set. In this example, QPI data,
-stored as a tuple of files ("*_intensity.txt" and "*_phase.txt")
+stored as a tuple of files ("\*_intensity.txt" and "\*_phase.txt")
 with commas as decimal separators, are converted to the numpy
 file format which is supported by qpformat.
 

examples/convert_txt2tif.py

@@ -3,7 +3,7 @@
 Qpformat can load hologram data from .tif image files. If your
 experimental hologram data are stored in a different file format,
 you can either request its implementation in qpformat by
-`creating an issue<https://github.com/RI-imaging/qpformat/issues/new>`_
+`creating an issue <https://github.com/RI-imaging/qpformat/issues/new>`__
 or you can modify this example script to your needs.
 
 This example must be executed with a directory as an

qpformat/file_formats/__init__.py

@@ -13,11 +13,22 @@
 from .single_tif_phasics import SingleTifPhasics
 
 
+
 class MultipleFormatsNotSupportedError(BaseException):
+    """Used when a folder contains series file formats
+
+    (see `GitHub issue #1 <https://github.com/RI-imaging/qpformat/issues/1>`__)
+    """
+    pass
+
+
+class UnknownFileFormatError(BaseException):
+    """Used when a file format could not be detected"""
     pass
 
 
 class SeriesFolder(SeriesData):
+    """Folder-based file format"""
     # storage_type is implemented as a property
 
     def __init__(self, *args, **kwargs):
@@ -141,9 +152,6 @@ def verify(path):
         return len(set(fifmts)) == 1
 
 
-class UnknownFileFormatError(BaseException):
-    pass
-
 
 # the order is important
 formats = [SeriesFolder,

qpformat/file_formats/series_hdf5_hyperspy.py

@@ -12,7 +12,7 @@ class HyperSpyNoDataFoundError(BaseException):
 
 
 class SeriesHdf5HyperSpy(SeriesData):
-    """HyperSpy file format
+    """HyperSpy files
 
     hyperspy.io_plugins.hspy
     """

qpformat/file_formats/series_hdf5_qpimage.py

@@ -5,6 +5,7 @@
 
 
 class SeriesHdf5Qpimage(SeriesData):
+    """Series qpimage files (hdf5-based)"""
     storage_type = "phase,amplitude"
 
     def __init__(self, *args, **kwargs):

qpformat/file_formats/series_zip_tif_holo.py

@@ -7,6 +7,7 @@
 
 
 class SeriesZipTifHolo(SeriesData):
+    """Zipped off-axis hologram .tif files"""
     storage_type = "hologram"
 
     def __init__(self, *args, **kwargs):

qpformat/file_formats/series_zip_tif_phasics.py

@@ -7,6 +7,7 @@
 
 
 class SeriesZipTifPhasics(SeriesData):
+    """Zipped Phasics .tif files ("SID PHA*.tif")"""
     storage_type = "phase,intensity"
 
     def __init__(self, *args, **kwargs):

qpformat/file_formats/single_hdf5_qpimage.py

@@ -5,6 +5,7 @@
 
 
 class SingleHdf5Qpimage(SingleData):
+    """Single qpimage files (hdf5-based)"""
     storage_type = "phase,amplitude"
 
     @property

qpformat/file_formats/single_npy_numpy.py

@@ -9,7 +9,7 @@
 
 
 class SingleNpyNumpy(SingleData):
-    """Field data stored in numpy's .npy file format
+    """Single numpy-based files (.npy format)
 
     The experimental data given in `path` consist of a single
     2D ndarray (no pickled objects). The ndarray is either

qpformat/file_formats/single_tif_holo.py

@@ -8,7 +8,7 @@
 
 
 class SingleTifHolo(SingleData):
-    """DataSet for off-axis hologram data"""
+    """Single off-axis hologram .tif files"""
     storage_type = "hologram"
 
     @staticmethod

qpformat/file_formats/single_tif_phasics.py

@@ -20,6 +20,7 @@ class LoadTifPhasicsError(BaseException):
 
 
 class SingleTifPhasics(SingleData):
+    """Single Phasics .tif files ("SID PHA*.tif")"""
     storage_type = "phase,intensity"
 
     def __init__(self, path, meta_data={}, *args, **kwargs):