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):

Factorize test for all reader
It should be possible to make common tests for the different format:

- read one file
- read multiple files
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

pip install -e .[dev]
parse_log_pytest
requirements.txt
pytest pytest-cov pytest-mock sphinx sphinx-gallery sphinx_rtd_theme numpydoc matplotlib
3.6
requirements.txt
pytest --no-header -rA --tb=line --color=no -p no:cacheprovider -W ignore::DeprecationWarning
alabaster==0.7.13
attrs==22.2.0
Babel==2.11.0
certifi==2021.5.30
charset-normalizer==2.0.12
coverage==6.2
cycler==0.11.0
docutils==0.18.1
idna==3.10
imagesize==1.4.1
importlib-metadata==4.8.3
iniconfig==1.1.1
Jinja2==3.0.3
kiwisolver==1.3.1
MarkupSafe==2.0.1
matplotlib==3.3.4
numpy==1.19.5
numpydoc==1.1.0
packaging==21.3
Pillow==8.4.0
pluggy==1.0.0
py==1.11.0
Pygments==2.14.0
pyparsing==3.1.4
pytest==7.0.1
pytest-cov==4.0.0
pytest-mock==3.6.1
python-dateutil==2.9.0.post0
pytz==2025.2
requests==2.27.1
six==1.17.0
snowballstemmer==2.2.0
spc @ git+https://github.com/glemaitre/spc.git@44b67d49e1e4fe9364e7cbce9a93086037703511
-e git+https://github.com/paris-saclay-cds/specio.git@bf3c46fb34575bb6df7860fb354d0fc173c30f18#egg=specio
Sphinx==5.3.0
sphinx-gallery==0.10.0
sphinx-rtd-theme==2.0.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jquery==4.1
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
tomli==1.2.3
typing_extensions==4.1.1
urllib3==1.26.20
zipp==3.6.0

name: specio
channels:
  - defaults
  - https://repo.anaconda.com/pkgs/main
  - https://repo.anaconda.com/pkgs/r
  - conda-forge
dependencies:
  - _libgcc_mutex=0.1=main
  - _openmp_mutex=5.1=1_gnu
  - ca-certificates=2025.2.25=h06a4308_0
  - certifi=2021.5.30=py36h06a4308_0
  - ld_impl_linux-64=2.40=h12ee557_0
  - libffi=3.3=he6710b0_2
  - libgcc-ng=11.2.0=h1234567_1
  - libgomp=11.2.0=h1234567_1
  - libstdcxx-ng=11.2.0=h1234567_1
  - ncurses=6.4=h6a678d5_0
  - openssl=1.1.1w=h7f8727e_0
  - pip=21.2.2=py36h06a4308_0
  - python=3.6.13=h12debd9_1
  - readline=8.2=h5eee18b_0
  - setuptools=58.0.4=py36h06a4308_0
  - sqlite=3.45.3=h5eee18b_0
  - tk=8.6.14=h39e8969_0
  - wheel=0.37.1=pyhd3eb1b0_0
  - xz=5.6.4=h5eee18b_1
  - zlib=1.2.13=h5eee18b_1
  - pip:
      - alabaster==0.7.13
      - attrs==22.2.0
      - babel==2.11.0
      - charset-normalizer==2.0.12
      - coverage==6.2
      - cycler==0.11.0
      - docutils==0.18.1
      - idna==3.10
      - imagesize==1.4.1
      - importlib-metadata==4.8.3
      - iniconfig==1.1.1
      - jinja2==3.0.3
      - kiwisolver==1.3.1
      - markupsafe==2.0.1
      - matplotlib==3.3.4
      - numpy==1.19.5
      - numpydoc==1.1.0
      - packaging==21.3
      - pillow==8.4.0
      - pluggy==1.0.0
      - py==1.11.0
      - pygments==2.14.0
      - pyparsing==3.1.4
      - pytest==7.0.1
      - pytest-cov==4.0.0
      - pytest-mock==3.6.1
      - python-dateutil==2.9.0.post0
      - pytz==2025.2
      - requests==2.27.1
      - six==1.17.0
      - snowballstemmer==2.2.0
      - spc==0.4.0
      - sphinx==5.3.0
      - sphinx-gallery==0.10.0
      - sphinx-rtd-theme==2.0.0
      - sphinxcontrib-applehelp==1.0.2
      - sphinxcontrib-devhelp==1.0.2
      - sphinxcontrib-htmlhelp==2.0.0
      - sphinxcontrib-jquery==4.1
      - sphinxcontrib-jsmath==1.0.1
      - sphinxcontrib-qthelp==1.0.3
      - sphinxcontrib-serializinghtml==1.1.5
      - tomli==1.2.3
      - typing-extensions==4.1.1
      - urllib3==1.26.20
      - zipp==3.6.0
prefix: /opt/conda/envs/specio

specio/plugins/tests/test_common.py::test_toy_data[/specio/specio/datasets/data/spectra.fsm-spectrum_shape0-wavelength_shape0] specio/plugins/tests/test_common.py::test_toy_data[/specio/specio/datasets/data/spectra.spc-spectrum_shape1-wavelength_shape1]
specio/plugins/tests/test_fsm.py::test_fsm_format
doc/_templates/class.rst doc/conf.py specio/plugins/spc.py examples/plot_read_multiple_files.py specio/plugins/fsm.py doc/_templates/numpydoc_docstring.py doc/_templates/function.rst doc/api.rst
doc/_templates/class.rst doc/conf.py specio/plugins/spc.py examples/plot_read_multiple_files.py specio/plugins/fsm.py doc/_templates/numpydoc_docstring.py doc/_templates/function.rst doc/api.rst