Repository: paris-saclay-cds/specio

Issue:
Factorize test for all reader
It should be possible to make common tests for the different format:

- read one file
- read multiple files

Discussion:

Patch:
diff --git a/doc/_templates/class.rst b/doc/_templates/class.rst
new file mode 100644
index 0000000..3eef974
--- /dev/null
+++ b/doc/_templates/class.rst
@@ -0,0 +1,16 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}==============
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+   {% endblock %}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>
diff --git a/doc/_templates/function.rst b/doc/_templates/function.rst
new file mode 100644
index 0000000..4ba355d
--- /dev/null
+++ b/doc/_templates/function.rst
@@ -0,0 +1,12 @@
+:mod:`{{module}}`.{{objname}}
+{{ underline }}====================
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. include:: {{module}}.{{objname}}.examples
+
+.. raw:: html
+
+    <div style='clear:both'></div>
diff --git a/doc/_templates/numpydoc_docstring.py b/doc/_templates/numpydoc_docstring.py
new file mode 100644
index 0000000..fd6a35f
--- /dev/null
+++ b/doc/_templates/numpydoc_docstring.py
@@ -0,0 +1,16 @@
+{{index}}
+{{summary}}
+{{extended_summary}}
+{{parameters}}
+{{returns}}
+{{yields}}
+{{other_parameters}}
+{{attributes}}
+{{raises}}
+{{warns}}
+{{warnings}}
+{{see_also}}
+{{notes}}
+{{references}}
+{{examples}}
+{{methods}}
diff --git a/doc/api.rst b/doc/api.rst
index cb37f66..932c673 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -2,24 +2,59 @@
 specio's user API
 ###################
 
-.. automodule:: specio.core.functions
+Spectra reader functions
+========================
 
-----
+These functions represent specio's main interface for the user. They provide a
+common API to read spectra data for a large variety of formats. All read
+functions accept keyword arguments, which are passed on to the format that does
+the actual work.  To see what keyword arguments are supported by a specific
+format, use the :func:`.help` function.
 
-.. autofunction:: specio.help
+Functions for reading:
 
-.. autofunction :: specio.show_formats
+  * :func:`.specread` - read a file with spectra from the specified uri
 
-----
+For a larger degree of control, specio provides a function
+:func:`.get_reader`. It returns an :class:`.Reader` object, which can be used
+to read data and meta data in a more controlled manner.  This also allows
+specific scientific formats to be exposed in a way that best suits that
+file-format.
 
-.. autofunction:: specio.specread
+Functions
+---------
 
-----
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
 
-.. autofunction:: specio.get_reader
+   specio.help
+   specio.show_formats
+   specio.specread
+   specio.get_reader
 
-----
+Classes
+-------
 
-.. autoclass:: specio.core.format.Reader
-    :inherited-members:
-    :members:
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   specio.core.format.Reader
+
+
+Example datasets
+================
+
+.. automodule:: specio.datasets
+    :no-members:
+    :no-inherited-members:
+
+.. currentmodule:: specio
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   datasets.load_spc_path
+   datasets.load_fsm_path
diff --git a/doc/conf.py b/doc/conf.py
index 34133ea..089c4b6 100755
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -47,6 +47,7 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
               'sphinx.ext.autosummary',
+              'sphinx.ext.intersphinx',
               'sphinx_gallery.gen_gallery',
               'numpydoc',
               'sphinx_issues',
@@ -62,19 +63,21 @@ autosummary_generate = True
 
 autodoc_default_flags = ['members', 'inherited-members']
 
+# intersphinx configuration
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/{.major}'.format(
+        sys.version_info), None),
+    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
+    'matplotlib': ('https://matplotlib.org/', None),
+}
+
+# sphinx-gallery configuration
 sphinx_gallery_conf = {
-    # path to your examples scripts
-    'examples_dirs': '../examples',
-    # path where to save gallery generated examples
-    'gallery_dirs': 'auto_examples',
-    # to make references clickable
     'doc_module': 'specio',
+    'backreferences_dir': os.path.join('generated'),
     'reference_url': {
-        'specio': None,
-        'matplotlib': 'http://matplotlib.org',
-        'numpy': 'http://docs.scipy.org/doc/numpy-1.11.0',
-        'scipy': 'http://docs.scipy.org/doc/scipy-0.18.0/reference'
-    }
+        'specio': None}
 }
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/examples/plot_read_multiple_files.py b/examples/plot_read_multiple_files.py
index e006a0e..b578887 100644
--- a/examples/plot_read_multiple_files.py
+++ b/examples/plot_read_multiple_files.py
@@ -10,13 +10,14 @@ folder.
 from __future__ import print_function
 
 import os
+import sys
 
 import matplotlib.pyplot as plt
 
 from specio import specread
 
 # Get the path to the data relatively to this example
-DATA_PATH = os.path.dirname(__file__)
+DATA_PATH = os.path.dirname(sys.argv[0])
 
 spc_filenames = os.path.join(DATA_PATH, 'data', '*.spc')
 print('The SPC files will be search in: {}'.format(spc_filenames))
diff --git a/specio/plugins/fsm.py b/specio/plugins/fsm.py
index bcb257a..9e11f7e 100644
--- a/specio/plugins/fsm.py
+++ b/specio/plugins/fsm.py
@@ -6,7 +6,10 @@
 
 from __future__ import absolute_import, print_function, division
 
+from os.path import basename
+
 import numpy as np
+from six import string_types
 
 from .. import formats
 from ..core import Format
@@ -267,6 +270,10 @@ class FSM(Format):
             wavelength = np.arange(meta['z_start'],
                                    meta['z_end'] + meta['z_delta'],
                                    meta['z_delta'])
+            if isinstance(fsm_file, string_types):
+                meta['filename'] = basename(fsm_file)
+            else:
+                meta['filename'] = basename(fsm_file.name)
 
             return Spectrum(spectrum, wavelength, meta)
 
diff --git a/specio/plugins/spc.py b/specio/plugins/spc.py
index c61fe41..53c2510 100644
--- a/specio/plugins/spc.py
+++ b/specio/plugins/spc.py
@@ -8,8 +8,10 @@ from __future__ import absolute_import, print_function, division
 
 import struct
 import warnings
+from os.path import basename
 
 import numpy as np
+from six import string_types
 
 from .. import formats
 from ..core import Format
@@ -91,7 +93,7 @@ class SPC(Format):
 
             return meta
 
-        def _spc_to_numpy(self, spc_file):
+        def _spc_to_numpy(self, spc_file, spc_filename):
             """Convert the SPC File data to spectrum data.
 
             Parameters
@@ -99,6 +101,9 @@ class SPC(Format):
             spc_file : spc.File
                 The SPC File to be converted.
 
+            spc_filename : string
+                The SPC filename to be added to the dictionary.
+
             Returns
             -------
             spectrum : util.Spectrum
@@ -106,6 +111,7 @@ class SPC(Format):
 
             """
             meta = self._meta_data_from_spc(spc_file)
+            meta['filename'] = basename(spc_filename)
             if spc_file.dat_fmt in ('gx-y', 'x-y'):
                 spectrum = np.squeeze([f.y for f in spc_file.sub])
                 wavelength = spc_file.x
@@ -121,7 +127,7 @@ class SPC(Format):
             import spc
             # Open the reader
             self._fp = self.request.get_local_filename()
-            self._data = self._spc_to_numpy(spc.File(self._fp))
+            self._data = self._spc_to_numpy(spc.File(self._fp), self._fp)
             self._length = len(self._data)
 
         def _close(self):


Test patch:
diff --git a/specio/plugins/tests/test_common.py b/specio/plugins/tests/test_common.py
new file mode 100644
index 0000000..bab8387
--- /dev/null
+++ b/specio/plugins/tests/test_common.py
@@ -0,0 +1,26 @@
+"""Common tests using the toy data."""
+
+# Copyright (c) 2017
+# Authors: Guillaume Lemaitre <guillaume.lemaitre@inria.fr>
+# License: BSD 3 clause
+
+from os.path import basename
+
+import pytest
+
+from specio import specread
+from specio.core import Spectrum
+from specio.datasets import load_fsm_path
+from specio.datasets import load_spc_path
+
+
+@pytest.mark.parametrize(
+    "filename,spectrum_shape,wavelength_shape",
+    [(load_fsm_path(), (7998, 1641), (1641,)),
+     (load_spc_path(), (1911,), (1911,))])
+def test_toy_data(filename, spectrum_shape, wavelength_shape):
+    spec = specread(filename)
+    assert isinstance(spec, Spectrum)
+    assert spec.spectrum.shape == spectrum_shape
+    assert spec.wavelength.shape == wavelength_shape
+    assert spec.meta['filename'] == basename(filename)
diff --git a/specio/plugins/tests/test_fsm.py b/specio/plugins/tests/test_fsm.py
index 1af2d16..b5fa2d2 100644
--- a/specio/plugins/tests/test_fsm.py
+++ b/specio/plugins/tests/test_fsm.py
@@ -28,12 +28,3 @@ def test_fsm_format():
     assert spec.spectrum.shape == (1641,)
     assert spec.wavelength.shape == (1641,)
     assert spec.spectrum[0] == pytest.approx(38.656551)
-
-
-@pytest.mark.parametrize(
-    "filename,spectrum_shape,wavelength_shape",
-    [(load_fsm_path(), (7998, 1641), (1641,))])
-def test_fsm_file(filename, spectrum_shape, wavelength_shape):
-    spec = specread(filename)
-    assert spec.spectrum.shape == spectrum_shape
-    assert spec.wavelength.shape == wavelength_shape