docs: lots of improvements

CHANGELOG

@@ -1,3 +1,6 @@
+0.3.0
+ - docs: automatically document all file format classes
+ - docs: add introduction and file format overview
 0.2.1
  - fix: regression when loading data from zip file
 0.2.0

docs/README.md

@@ -8,3 +8,8 @@ To compile the documentation, run
 
     sphinx-build . _build
 
+Notes
+=====
+To view the sphinx inventory of qpformat, run
+
+   python -m sphinx.ext.intersphinx 'http://qpformat.readthedocs.io/en/latest/objects.inv'

docs/conf.py

@@ -51,6 +51,7 @@
 # Order class attributes and functions in separate blocks
 autodoc_member_order = 'bysource'
 autodoc_mock_imports = install_requires
+autoclass_content = 'both'
 
 # Display link to GitHub repo instead of doc on rtfd
 rst_prolog = """
@@ -203,6 +204,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"python": ('https://docs.python.org/', None),
+                       "hyperspy": ('http://hyperspy.readthedocs.io/en/stable/', None),
                        "numpy": ('http://docs.scipy.org/doc/numpy', None),
                        "scipy": ('https://docs.scipy.org/doc/scipy/reference/', None),
                        "skimage": ('http://scikit-image.org/docs/stable/', None),

docs/extensions/qpformat_readers.py

@@ -17,7 +17,7 @@
 from sphinx.util.nodes import nested_parse_with_titles
 from docutils import nodes
 
-from qpformat.file_formats import formats_dict
+from qpformat.file_formats import formats_dict, SeriesData
 
 
 class Base(Directive):
@@ -43,9 +43,29 @@ class AutodocFormats(Base):
     def generate_rst(self):
         rst = []
 
+        refdir = [a for a in dir(SeriesData) if not a.startswith("_")]
+
         for key in sorted(formats_dict.keys()):
+            # get any public methods that are not in the base class
+            cdir = [a for a in dir(formats_dict[key]) if not a.startswith("_")]
+            cdir = [a for a in cdir if not a in refdir]
+            # get important public attributes
+            udcand = ["is_series", "storage_type"]
+            udir = [a for a in udcand if hasattr(formats_dict[key], a)]
+            # remove attributes from cdir to avoid redundant docs
+            [cdir.remove(a) for a in udir if a in cdir]
             rst.append("")
+            # headint
+            rst.append(key)
+            rst.append("-"*len(key))
+            # autodoc
             rst.append(".. autoclass:: qpformat.file_formats.{}".format(key))
+            if cdir:
+                rst.append("    :members: {}".format(", ".join(cdir)))
+            if udir:
+                rst.append("")
+                for u in udir:
+                    rst.append("    .. autoattribute:: {}".format(u))
             rst.append("")
 
         return rst
@@ -56,7 +76,7 @@ def generate_rst(self):
         rst = []
 
         rst.append(".. csv-table::")
-        rst.append("    :header: Class, Data type, Description".format())
+        rst.append("    :header: Class, Storage type, Description".format())
         rst.append("    :widths: 2, 2, 6")
         rst.append("    :delim: tab")
         rst.append("")
@@ -65,7 +85,7 @@ def generate_rst(self):
             cl = formats_dict[key]
             datatype = cl.storage_type
             if not isinstance(datatype, str):
-                datatype = "multiple"
+                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]))
 

docs/sec_code_reference.rst

@@ -13,19 +13,23 @@ module-level
 
 file format base classes
 ========================
+SeriesData
+----------
+.. autoclass:: qpformat.file_formats.dataset.SeriesData
+    :members:
+
 SingleData
 ----------
 .. autoclass:: qpformat.file_formats.dataset.SingleData
     :inherited-members:
 
-SeriesData
-----------
-.. autoclass:: qpformat.file_formats.dataset.SeriesData
-    :members:
 
 
 file format readers
 ===================
+All file formats inherit from :class:`qpformat.file_formats.dataset.SeriesData`
+(and/or :class:`qpformat.file_formats.dataset.SingleData`).
+
 .. autodoc_qpformats::
 
 

docs/sec_introduction.rst

@@ -20,7 +20,9 @@ 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_formats:
+
 Supported file formats
 ======================
 .. qpformats::
-

qpformat/file_formats/__init__.py

@@ -13,7 +13,6 @@
 from .single_tif_phasics import SingleTifPhasics
 
 
-
 class MultipleFormatsNotSupportedError(BaseException):
     """Used when a folder contains series file formats
 
@@ -28,7 +27,7 @@ class UnknownFileFormatError(BaseException):
 
 
 class SeriesFolder(SeriesData):
-    """Folder-based file format"""
+    """Folder-based wrapper file format"""
     # storage_type is implemented as a property
 
     def __init__(self, *args, **kwargs):
@@ -115,6 +114,7 @@ def _search_files(path):
 
     @property
     def files(self):
+        """List of files (only supported file formats)"""
         if self._files is None:
             fifo = SeriesFolder._search_files(self.path)
             self._files = [ff[0] for ff in fifo]
@@ -123,6 +123,7 @@ def files(self):
 
     @property
     def storage_type(self):
+        """The storage type depends on the wrapped file format"""
         ds = self._get_dataset(0)
         return ds.storage_type
 
@@ -145,14 +146,13 @@ def verify(path):
         """Verify folder file format
 
         The folder file format is only valid when
-        - there is only one file format present
+        there is only one file format present.
         """
         fifo = SeriesFolder._search_files(path)
         fifmts = [ff[1] for ff in fifo]
         return len(set(fifmts)) == 1
 
 
-
 # the order is important
 formats = [SeriesFolder,
            SingleHdf5Qpimage,

qpformat/file_formats/dataset.py

@@ -9,26 +9,26 @@
 
 
 class SeriesData(object):
+    """Series data file format base class
+
+    Parameters
+    ----------
+    path: str or pathlib.Path
+        Path to the experimental data file.
+    meta_data: dict
+        Dictionary containing meta data.
+        see :py:class:`qpimage.META_KEYS`.
+    as_type: str
+        Defines the data type that the input data is casted to.
+        The default is "float32" which saves memory. If high
+        numerical accuracy is required (does not apply for a
+        simple 2D phase analysis), set this to double precision
+        ("float64").
+    """
     __meta__ = abc.ABCMeta
     is_series = True
 
     def __init__(self, path, meta_data={}, holo_kw={}, as_type="float32"):
-        """Experimental data set
-
-        Parameters
-        ----------
-        path: str or pathlib.Path
-            Path to the experimental data file.
-        meta_data: dict
-            Dictionary containing meta data.
-            see :py:class:`qpimage.META_KEYS`.
-        as_type: str
-            Defines the data type that the input data is casted to.
-            The default is "float32" which saves memory. If high
-            numerical accuracy is required (does not apply for a
-            simple 2D phase analysis), set this to double precision
-            ("float64").
-        """
         self.as_type = as_type
         if isinstance(path, (str, pathlib.Path)):
             self.path = pathlib.Path(path).resolve()
@@ -239,6 +239,22 @@ def verify(path):
 
 
 class SingleData(SeriesData):
+    """Single data file format base class
+
+    Parameters
+    ----------
+    path: str or pathlib.Path
+        Path to the experimental data file.
+    meta_data: dict
+        Dictionary containing meta data.
+        see :py:class:`qpimage.META_KEYS`.
+    as_type: str
+        Defines the data type that the input data is casted to.
+        The default is "float32" which saves memory. If high
+        numerical accuracy is required (does not apply for a
+        simple 2D phase analysis), set this to double precision
+        ("float64").
+    """
     __meta__ = abc.ABCMeta
     is_series = False
 

qpformat/file_formats/series_hdf5_hyperspy.py

@@ -12,9 +12,10 @@ class HyperSpyNoDataFoundError(BaseException):
 
 
 class SeriesHdf5HyperSpy(SeriesData):
-    """HyperSpy files
+    """HyperSpy hologram series (HDF5 format)
 
-    hyperspy.io_plugins.hspy
+    HyperSpy has its :ref:`own implementation
+    <hyperspy:electron-holography-label>` to read this file format.
     """
     storage_type = "hologram"
 
@@ -89,10 +90,7 @@ def get_qpimage_raw(self, idx=0):
 
     @staticmethod
     def verify(path):
-        """Verify that `path` has the hyperspy file format
-
-        Returns `True` if the file format matches.
-        """
+        """Verify that `path` has the HyperSpy file format"""
         valid = False
         try:
             h5 = h5py.File(path, mode="r")

qpformat/file_formats/series_hdf5_qpimage.py

@@ -5,7 +5,7 @@
 
 
 class SeriesHdf5Qpimage(SeriesData):
-    """Series qpimage files (hdf5-based)"""
+    """Qpimage series (HDF5 format)"""
     storage_type = "phase,amplitude"
 
     def __init__(self, *args, **kwargs):
@@ -64,10 +64,7 @@ def get_qpimage_raw(self, idx):
 
     @staticmethod
     def verify(path):
-        """Verify that `path` has the qpimage file format
-
-        Returns `True` if the file format matches.
-        """
+        """Verify that `path` has the qpimage series file format"""
         valid = False
         try:
             h5 = h5py.File(path, mode="r")

qpformat/file_formats/series_zip_tif_holo.py

@@ -7,7 +7,11 @@
 
 
 class SeriesZipTifHolo(SeriesData):
-    """Zipped off-axis hologram .tif files"""
+    """Off-axis hologram series (zipped TIFF files)
+
+    The data are stored as multiple TIFF files
+    (:class:`qpformat.file_formats.SingleTifHolo`) in a zip file.
+    """
     storage_type = "hologram"
 
     def __init__(self, *args, **kwargs):
@@ -48,6 +52,7 @@ def _index_files(path):
 
     @property
     def files(self):
+        """List of hologram data file names in the input zip file"""
         if self._files is None:
             self._files = SeriesZipTifHolo._index_files(self.path)
         return self._files
@@ -59,7 +64,7 @@ def get_qpimage_raw(self, idx):
 
     @staticmethod
     def verify(path):
-        """Verify hologram zip tif file format"""
+        """Verify that `path` is a zip file containing TIFF files"""
         valid = False
         try:
             zf = zipfile.ZipFile(path)

qpformat/file_formats/series_zip_tif_phasics.py

@@ -7,7 +7,11 @@
 
 
 class SeriesZipTifPhasics(SeriesData):
-    """Zipped Phasics .tif files ("SID PHA*.tif")"""
+    """Phasics series data (zipped "SID PHA*.tif" files)
+
+    The data are stored as multiple TIFF files
+    (:class:`qpformat.file_formats.SingleTifPhasics`) in a zip file.
+    """
     storage_type = "phase,intensity"
 
     def __init__(self, *args, **kwargs):
@@ -49,6 +53,7 @@ def _index_files(path):
 
     @property
     def files(self):
+        """List of Phasics tif file names in the input zip file"""
         if self._files is None:
             self._files = SeriesZipTifPhasics._index_files(self.path)
         return self._files
@@ -65,7 +70,7 @@ def get_time(self, idx):
 
     @staticmethod
     def verify(path):
-        """Verify phasics zip tif file format"""
+        """Verify that `path` is a zip file with Phasics TIFF files"""
         valid = False
         try:
             zf = zipfile.ZipFile(path)

qpformat/file_formats/single_hdf5_qpimage.py

@@ -5,7 +5,11 @@
 
 
 class SingleHdf5Qpimage(SingleData):
-    """Single qpimage files (hdf5-based)"""
+    """Qpimage single (HDF5 format)
+
+    See the documentation of :ref:`qpimage <qpimage:index>` for more
+    information.
+    """
     storage_type = "phase,amplitude"
 
     @property
@@ -52,10 +56,7 @@ def get_qpimage_raw(self, idx=0):
 
     @staticmethod
     def verify(path):
-        """Verify that `path` has the qpimage file format
-
-        Returns `True` if the file format matches.
-        """
+        """Verify that `path` has the qpimage file format"""
         valid = False
         try:
             h5 = h5py.File(path, mode="r")