[doc] rework documentation

- add an example file to present a quick start documentation
- group API in a dedicated place
- several small fix on doc (types, param name not specify for :type: ...)

doc/conf.py

@@ -34,7 +34,7 @@ project = u'tomoscan'
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be
+# Add any Sphinx extension modules names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
@@ -93,7 +93,7 @@ exclude_patterns = ['build', '**.ipynb_checkpoints']
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
-# If true, the current module name will be prepended to all description
+# If true, the current modules name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
@@ -104,7 +104,7 @@ exclude_patterns = ['build', '**.ipynb_checkpoints']
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-# A list of ignored prefixes for module index sorting.
+# A list of ignored prefixes for modules index sorting.
 #modindex_common_prefix = []
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
@@ -169,7 +169,7 @@ html_logo = "img/tomoscan.png"
 # template names.
 #html_additional_pages = {}
 
-# If false, no module index is generated.
+# If false, no modules index is generated.
 #html_domain_indices = True
 
 # If false, no index is generated.
@@ -253,7 +253,7 @@ latex_elements = {
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
-# If false, no module index is generated.
+# If false, no modules index is generated.
 #latex_domain_indices = True
 
 
@@ -289,7 +289,7 @@ texinfo_documents = [
 # Documents to append as an appendix to all manuals.
 #texinfo_appendices = []
 
-# If false, no module index is generated.
+# If false, no modules index is generated.
 #texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.

doc/examples.rst

+Examples
+========
+
+
+Quick Start
+-----------
+
+The goal is to have an unified API to access data from an EDF acquisition or an HDF5 acquisition.
+
+EDF scan
+''''''''
+
+To create a 'Scan' object from EDF you have to use the :class:`EDFTomoScan` class and provide the path to the acquisition:
+
+.. code-block:: python
+
+    scan = EDFTomoScan(scan=folder_path)
+
+
+.. warning:: Browsing EDF files is based on several convention at ESRF.
+             The most important one is that the acquisition 'identification' - which is the folder name is repeated in the file names.
+             For example if we have an acquisition names 'acq_0005' we expect edf file prefix to be 'acq_0005' too.
+
+.. warning:: The :class:`EDFTomoScan` as been tested on EDF single frame files. It wouldn't be surprising if it fails on EDF multiple frames files.
+
+
+HDF5 scan
+'''''''''
+
+.. warning:: The HDF5 managed by tomoscan should be NXTomo compliant. So if your files come directly from bliss you should first convert them using `nxtomomill <https://gitlab.esrf.fr/tomotools/nxtomomill>`_.
+             See `tomoh52nx tutorial <https://tomotools.gitlab-pages.esrf.fr/nxtomomill/tutorials/tomoh52nx.html>`_.
+
+
+For HDF5 you have to provide the file you want to tread (.hdf5, .h5, .nx...) and an entry as HDF5 files can contains several acquisition.
+
+
+.. code-block:: python
+
+    scan = HDF5TomoScan(scan=hdf5_files, entry='entry0000')
+
+
+
+
+
+TomoScanBase API
+''''''''''''''''
+
+Both :class:`EDFTomoScan` and :class:`HDF5TomoScan` are implementing the TomoScanBase interface.
+This allow you to access flattely data from EDF or HDF5 regardless of the type of acquisition.
+
+
+You can access:
+
+ * projections:
+
+    .. code-block:: python
+
+        scan.projections
+
+ * flats:
+
+    .. code-block:: python
+
+        scan.flats
+
+ * darks:
+
+    .. code-block:: python
+
+        scan.darks
+
+ * incoming beam energy:
+
+    .. code-block:: python
+
+        scan.energy
+
+ * detector pixel size:
+
+    .. code-block:: python
+
+        scan.pixel_size
+
+ * ...
\ No newline at end of file

doc/index.rst

@@ -3,10 +3,20 @@ tomoscan
 
 tomoscan aims to provide an unified interface to read tomography data from .edf or .hdf5 (NXtomo) acquisitions.
 
+This one tool to get an unified API from EDF or HDF5 acquisitions.
+
+You can also convert EDF dataset to obtain an HDF5 - NXTomo compliant file by using `nxtomomill <https://gitlab.esrf.fr/tomotools/nxtomomill>`_.
+See the `tomoedf2nx tutorial <https://tomotools.gitlab-pages.esrf.fr/nxtomomill/tutorials/tomoedf2nx.html>`_.
+tomoscan will not produce any other file.
+
+
 .. toctree::
-   :maxdepth: 4
+   :hidden:
+
+   modules/index.rst
+   examples
+
+
+:doc:`examples`
 
-   esrf
-   scanbase
-   scanfactory
-   unitsystem
+:doc:`modules/index`

doc/modules/index.rst

+API
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   esrf.rst
+   scanbase.rst
+   scanfactory.rst
+   unitsystem.rst
\ No newline at end of file

doc/tutorials/hdf5_scan.ipynb

-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.7.3"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}
-%% Cell type:code id: tags:
-
-``` python
-```

tomoscan/esrf/edfscan.py

@@ -52,11 +52,11 @@ class EDFTomoScan(TomoScanBase):
     TomoScanBase instanciation for scan defined from .edf files
 
     :param scan: path to the root folder containing the scan.
-    :type: Union[str,None]
+    :type scan: Union[str,None]
     :param n_frames: Number of frames in each EDF file.
         If not provided, it will be inferred by reading the files.
         In this case, the frame number is guessed from the file name.
-    :type: Union[int, None]=None
+    :type n_frames: Union[int, None]=None
     """
     _TYPE = 'edf'
 
@@ -264,10 +264,10 @@ class EDFTomoScan(TomoScanBase):
         ending by .edf
 
         :param scan: is the path to the folder of acquisition
-        :type: str
+        :type scan: str
         :param n_frames: Number of frames in each EDF file.
             If not provided, it is inferred by reading each file.
-        :type: int
+        :type n_frames: int
         :return: dict of radios files with radio index as key and file as value
         :rtype: dict
         """
@@ -480,11 +480,11 @@ class EDFTomoScan(TomoScanBase):
         """
 
         :param scan_path:
-        :type: str
+        :type scan_path: str
         :param prefix: ref / flat field file prefix
-        :type: str
+        :type prefix: str
         :param file_ext: ref / flat field file extension
-        :type: str
+        :type file_ext: str
         :return: list of refs as silx's `DataUrl`
         """
         res = {}
@@ -514,11 +514,11 @@ class EDFTomoScan(TomoScanBase):
         """
 
         :param scan_path:
-        :type: str
+        :type scan_path: str
         :param prefix: ref / flat field file prefix
-        :type: str
+        :type prefix: str
         :param file_ext: ref / flat field file extension
-        :type: str
+        :type file_ext: str
         :return: list of refs as silx's `DataUrl`
         """
         res = {}
@@ -575,11 +575,11 @@ class EDFTomoScan(TomoScanBase):
         :param ref_file: the refXXXX_YYYY which should contain information
                          about the scan.
         :param key: the key (information) we are looking for
-        :type: str
+        :type key: str
         :param type_: requestde out type if the information is found
         :type type_: return type if the information is found.
         :param key_aliases: aliases of the key in the different file
-        :type: list
+        :type key_aliases: list
         :return: the requested information or None if not found
         """
         info_aliases = [key]

tomoscan/esrf/hdf5scan.py

@@ -651,11 +651,9 @@ class HDF5TomoScan(TomoScanBase):
         """
         Return a compacted view of projection frames.
 
-        Returns
-        --------
-        merged_projections: dict
-            Dictionary where the key is a list of indices, and the value
+        :return: Dictionary where the key is a list of indices, and the value
             is the corresponding `silx.io.url.DataUrl` with merged data_slice
+        :rtype: dict
         """
         if self._projections_compacted is None:
             self._projections_compacted = get_compacted_dataslices(self.projections)

tomoscan/esrf/utils.py

@@ -41,7 +41,7 @@ def get_parameters_frm_par_or_info(file_: str) -> dict:
     their values as values
 
     :param file_: path to the file to parse
-    :type:str
+    :type file_: str
     :raises: ValueError when fail to parse some line.
     """
     assert os.path.exists(file_) and os.path.isfile(file_)
@@ -67,15 +67,17 @@ def get_parameters_frm_par_or_info(file_: str) -> dict:
     return ddict
 
 
-def extract_urls_from_edf(file_: str, start_index: Union[None, int], n_frames: Union[int, None]=None) -> dict:
-    """return one DataUrl for each frame contain in the file_
+def extract_urls_from_edf(file_: str, start_index: Union[None, int],
+                          n_frames: Union[int, None]=None) -> dict:
+    """
+    return one DataUrl for each frame contain in the file_
 
     :param file_: path to the file to parse
-    :type:str
+    :type file_: str
     :param n_frames: Number of frames in each edf file (inferred if not told)
-    :type: Union[int, None]
+    :type n_frames: Union[int, None]
     :param start_index:
-    :type: Union[None,start_index]
+    :type start_index: Union[None,start_index]
     """
     res = {}
     index = 0 if start_index is None else start_index
@@ -96,17 +98,12 @@ def get_compacted_dataslices(urls):
     how to load the data: `{indices_set: data_location}`
     where `data_location` contains contiguous indices.
 
-    Parameters
-    -----------
-    urls: dict
-        Dictionary where the key is an integer and the value is a silx `DataUrl`.
-
-    Returns
-    --------
-    merged_urls: dict
-        Dictionary where the key is a list of indices, and the value
-        is the corresponding `silx.io.url.DataUrl` with merged data_slice
+    :param dict urls: Dictionary where the key is an integer and the value is
+                      a silx `DataUrl`.
 
+    :return: Dictionary where the key is a list of indices, and the value is
+             the corresponding `silx.io.url.DataUrl` with merged data_slice
+    :rtype: dict
     """
     def _convert_to_slice(idx):
         if numpy.isscalar(idx):

tomoscan/scanbase.py

@@ -21,7 +21,7 @@
 # THE SOFTWARE.
 #
 #############################################################################*/
-"""This module contains base class for TomoScanBase"""
+"""This modules contains base class for TomoScanBase"""
 
 __authors__ = ["H.Payno"]
 __license__ = "MIT"
@@ -51,7 +51,7 @@ class TomoScanBase:
     projections, dark and flat field...
 
     :param scan: path to the root folder containing the scan.
-    :type: Union[str,None]
+    :type scan: Union[str,None]
     """
     DICT_TYPE_KEY = 'type'
 
@@ -236,7 +236,7 @@ class TomoScanBase:
         Load properties contained in the dictionnary.
 
         :param _dict: dictionary to load
-        :type: dict
+        :type _dict: dict
         :return: self
         :raises: ValueError if dict is invalid
         """
@@ -247,8 +247,9 @@ class TomoScanBase:
 
         :param :class:`.ScanBase` other: instance to compare with 
         :return: True if instance are equivalent
-        :note: we cannot use the __eq__ function because this object need to be
-               pickable
+
+        ..note:: we cannot use the __eq__ function because this object need to be
+                 pickable
         """
         return (
             isinstance(other, self.__class__) or isinstance(self, other.__class__) and
@@ -274,23 +275,29 @@ class TomoScanBase:
         map given urls to an angle regarding scan_range and number of projection.
         We take the hypothesis that 'extra projection' are taken regarding the
         'id19' policy:
+
          * If the acquisition has a scan range of 360 then:
+
             * if 4 extra projection, the angles are (270, 180, 90, 0)
+
             * if 5 extra projection, the angles are (360, 270, 180, 90, 0)
+
          * If the acquisition has a scan range of 180 then:
+
             * if 2 extra projections: the angles are (90, 0)
+
             * if 3 extra projections: the angles are (180, 90, 0)
 
-        :warning: each url should contain only one radio.
+        ..warning:: each url should contain only one radio.
 
         :param urls: dict with all the urls. First url should be
                      the first radio acquire, last url should match the last
                      radio acquire.
-        :type: dict
+        :type urls: dict
         :param n_projection: number of projection for the sample.
-        :type: int
+        :type n_projection: int
         :param scan_range: acquisition range (usually 180 or 360)
-        :type: float
+        :type scan_range: float
         :return: angle in degree as key and url as value
         :rtype: dict
 

tomoscan/test/utils.py

@@ -27,7 +27,7 @@
 # THE SOFTWARE.
 
 
-__doc__ = """test module for pyFAI."""
+__doc__ = """test modules for pyFAI."""
 __authors__ = ["Jérôme Kieffer", "Valentin Valls", "Henri Payno"]
 __license__ = "MIT"
 __copyright__ = "European Synchrotron Radiation Facility, Grenoble, France"