diff options
Diffstat (limited to 'doc')
33 files changed, 137 insertions, 61 deletions
diff --git a/doc/source/Tutorials/io.rst b/doc/source/Tutorials/io.rst index 41a0dd3..4c54bba 100644 --- a/doc/source/Tutorials/io.rst +++ b/doc/source/Tutorials/io.rst @@ -324,6 +324,34 @@ For example to process all top-level groups of an HDF5 file: Note that the method with the `retry` decorator has to be idempotent as it can be executed several times for one call. +An equivalent decorator exists for context managers + +.. code-block:: python + + import silx.io.h5py_utils + + @silx.io.h5py_utils.retry_contextmanager() + def measurement_context(filename, name): + """The method will be entered again if + any HDF5 IO fails. + """ + with silx.io.h5py_utils.File(filename) as h5file: + yield h5file[name]["measurement"] + +Generator functions need to have a `start_index` parameter + +.. code-block:: python + + import silx.io.h5py_utils + + @silx.io.h5py_utils.retry() + def iter_measurement(filename, names, start_index=0): + """The method will be iterated again if any HDF5 + IO fails, possibly with a different start index. + """ + with silx.io.h5py_utils.File(filename) as h5file: + for name in names[start_index:]: + yield h5file[name]["measurement"] Additional resources -------------------- diff --git a/doc/source/conf.py b/doc/source/conf.py index 7e173f3..2d242e9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,6 +1,5 @@ -# -*- coding: utf-8 -*- # /*########################################################################## -# Copyright (C) 2015-2019 European Synchrotron Radiation Facility +# Copyright (C) 2015-2022 European Synchrotron Radiation Facility # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to deal @@ -32,25 +31,16 @@ autogenerated file. All configuration values have a default; values that are commented out serve to show the default.""" -import sys +import importlib import os -import os.path -import glob -import subprocess +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # sys.path.insert(0, os.path.abspath('.')) project = u'silx' -try: - import silx - project_dir = os.path.abspath(os.path.join(__file__, "..", "..", "..")) - build_dir = os.path.abspath(silx.__file__) - if not build_dir.startswith(project_dir): - raise RuntimeError("%s looks to come from the system. Fix your PYTHONPATH and restart sphinx." % project) -except ImportError: - raise RuntimeError("%s is not on the path. Fix your PYTHONPATH and restart sphinx." % project) +import silx # Disable deprecation warnings: # It avoid to spam documentation logs with deprecation warnings. @@ -79,9 +69,13 @@ extensions = [ 'sphinxext-archive', 'snapshotqt_directive', 'nbsphinx' - ] +if importlib.util.find_spec('sphinx_autodoc_typehints'): + extensions.append('sphinx_autodoc_typehints') + + always_document_param_types = True + autodoc_member_order = 'bysource' # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/ext/snapshotqt_directive.py b/doc/source/ext/snapshotqt_directive.py index 84b3ac6..2a40992 100644 --- a/doc/source/ext/snapshotqt_directive.py +++ b/doc/source/ext/snapshotqt_directive.py @@ -1,4 +1,3 @@ -# coding: utf-8 # /*########################################################################## # # Copyright (c) 2004-2019 European Synchrotron Radiation Facility @@ -31,7 +30,6 @@ Configuration variable in conf.py: the documentation source directory (i.e., the directory of conf.py) (default: '..'). """ -from __future__ import absolute_import __authors__ = ["H. Payno", "T. Vincent"] __license__ = "MIT" diff --git a/doc/source/ext/sphinxext-archive.py b/doc/source/ext/sphinxext-archive.py index dc1c2c8..39004e0 100644 --- a/doc/source/ext/sphinxext-archive.py +++ b/doc/source/ext/sphinxext-archive.py @@ -1,4 +1,3 @@ -# coding: utf-8 # /*########################################################################## # # Copyright (c) 2017 European Synchrotron Radiation Facility diff --git a/doc/source/install.rst b/doc/source/install.rst index 0841c2a..db86ac1 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -7,15 +7,15 @@ programming language. This table summarizes the support matrix of silx: -+------------+--------------+----------------------------+ -| System | Python vers. | Qt and its bindings | -+------------+--------------+----------------------------+ -| `Windows`_ | 3.6-3.9 | PyQt5.6+, PySide2, PySide6 | -+------------+--------------+----------------------------+ -| `MacOS`_ | 3.6-3.9 | PyQt5.6+, PySide2, PySide6 | -+------------+--------------+----------------------------+ -| `Linux`_ | 3.6-3.9 | PyQt5.3+, PySide2, PySide6 | -+------------+--------------+----------------------------+ ++------------+--------------+-----------------------------+ +| System | Python vers. | Qt and its bindings | ++------------+--------------+-----------------------------+ +| `Windows`_ | 3.6-3.9 | PyQt5.6+, PySide6, PyQt6.3+ | ++------------+--------------+-----------------------------+ +| `MacOS`_ | 3.6-3.9 | PyQt5.6+, PySide6, PyQt6.3+ | ++------------+--------------+-----------------------------+ +| `Linux`_ | 3.6-3.9 | PyQt5.3+, PySide6, PyQt6.3+ | ++------------+--------------+-----------------------------+ For the description of *silx* dependencies, see the Dependencies_ section. @@ -66,8 +66,8 @@ The mandatory dependencies are: The GUI widgets depend on the following extra packages: * A Qt binding: either `PyQt5 <https://riverbankcomputing.com/software/pyqt/intro>`_, - `PySide2 <https://pypi.org/project/PySide2/>`_, or - `PySide6 <https://pypi.org/project/PySide6/>`_ + `PySide6 <https://pypi.org/project/PySide6/>`_ or + `PyQt6 <https://pypi.org/project/PyQt6/>`_ * `matplotlib <http://matplotlib.org/>`_ * `PyOpenGL <http://pyopengl.sourceforge.net/>`_ * `qt_console <https://pypi.org/project/qtconsole>`_ @@ -289,32 +289,46 @@ To set the environment variables, type on the command line: Advanced build options ++++++++++++++++++++++ -In case you want more control over the build procedure, the build command is: +Advanced options can be set through the following environment variables: -.. code-block:: bash - - python setup.py build +.. list-table:: + :widths: 1 4 + :header-rows: 1 -There are few advanced options to ``setup.py build``: + * - Environment variable + - Description + * - ``SILX_WITH_OPENMP`` + - Whether or not to compile Cython code with OpenMP support (default: ``True`` except on macOS where it is ``False``) + * - ``SILX_FORCE_CYTHON`` + - Whether or not to force re-generating the C/C++ source code from Cython files (default: ``False``). + * - ``SPECFILE_USE_GNU_SOURCE`` + - Whether or not to use a cleaner locale independent implementation of :mod:`silx.io.specfile` by using `_GNU_SOURCE=1` + (default: ``False``; POSIX operating system only). + * - ``SILX_FULL_INSTALL_REQUIRES`` + - Set it to put all dependencies as ``install_requires`` (For packaging purpose). + * - ``SILX_INSTALL_REQUIRES_STRIP`` + - Comma-separated list of package names to remove from ``install_requires`` (For packaging purpose). +.. note:: Boolean options are passed as ``True`` or ``False``. -* ``--no-cython``: Prevent Cython (even if installed) from re-generating the C source code. - Use the one provided by the development team. -* ``--no-openmp``: Recompiles the Cython code without OpenMP support (default for MacOSX). -* ``--openmp``: Recompiles the Cython code with OpenMP support (default for Windows and Linux). -Package the build into a wheel and install it: +Package the build into a wheel and install it (this requires to install the `build <https://pypa-build.readthedocs.io>`_ package): .. code-block:: bash - python setup.py bdist_wheel + python -m build --wheel pip install dist/silx*.whl To build the documentation, using `Sphinx <http://www.sphinx-doc.org/>`_: .. code-block:: bash - python setup.py build build_doc + pip install . # Make sure to install the same version as the source + sphinx-build doc/source/ build/html + +.. note:: + To re-generate the example script screenshots, build the documentation with the + environment variable ``DIRECTIVE_SNAPSHOT_QT`` set to ``True``. Testing +++++++ diff --git a/doc/source/license.rst b/doc/source/license.rst index 760be91..2e79bc3 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -4,6 +4,18 @@ License The source code of *silx* is licensed under the `MIT <https://opensource.org/licenses/MIT>`_ license: .. include:: ../../LICENSE + :literal: + +Note: + The silx toolkit is a software library and one of its goals is not to impose any license to the end user. + + silx follows the permissive MIT license although it may include contributions following other licenses not interfering with the previous goal. + Detailed information can be found in the copyright file. + + silx uses the Qt library for its graphical user interfaces. + A word of caution is to be provided. + If users develop and distribute software using modules accessing Qt by means of Riverbank Computing Qt bindings PyQt4 or PyQt5, those users will be conditioned by the license of their PyQt4/5 software (GPL or commercial). + If the end user does not own a commercial license of PyQt4 or PyQt5 and wishes to be free of any distribution condition, (s)he should be able to use PySide2 because it uses the LGPL license. The following list provides the copyright and license of the different source files of the project: diff --git a/doc/source/modules/gui/data/img/ArrayTableWidget.png b/doc/source/modules/gui/data/img/ArrayTableWidget.png Binary files differindex e7bb2a9..138d189 100644 --- a/doc/source/modules/gui/data/img/ArrayTableWidget.png +++ b/doc/source/modules/gui/data/img/ArrayTableWidget.png diff --git a/doc/source/modules/gui/data/img/DataViewer.png b/doc/source/modules/gui/data/img/DataViewer.png Binary files differindex 7980de9..6d0da71 100644 --- a/doc/source/modules/gui/data/img/DataViewer.png +++ b/doc/source/modules/gui/data/img/DataViewer.png diff --git a/doc/source/modules/gui/icons.rst b/doc/source/modules/gui/icons.rst index cb8e044..238c724 100644 --- a/doc/source/modules/gui/icons.rst +++ b/doc/source/modules/gui/icons.rst @@ -49,6 +49,8 @@ Available icons - add-shape-polygon * - |add-shape-rectangle| - add-shape-rectangle + * - |add-shape-rotated-rectangle| + - add-shape-rotated-rectangle * - |add-shape-unknown| - add-shape-unknown * - |add-shape-vertical| @@ -315,6 +317,10 @@ Available icons - rotate-3d * - |rudder| - rudder + * - |scale-auto| + - scale-auto + * - |scale-fixed| + - scale-fixed * - |selected| - selected * - |shape-circle-solid| @@ -421,6 +427,7 @@ Available icons .. |add-shape-point| image:: ../../../../src/silx/resources/gui/icons/add-shape-point.png .. |add-shape-polygon| image:: ../../../../src/silx/resources/gui/icons/add-shape-polygon.png .. |add-shape-rectangle| image:: ../../../../src/silx/resources/gui/icons/add-shape-rectangle.png +.. |add-shape-rotated-rectangle| image:: ../../../../src/silx/resources/gui/icons/add-shape-rotated-rectangle.png .. |add-shape-unknown| image:: ../../../../src/silx/resources/gui/icons/add-shape-unknown.png .. |add-shape-vertical| image:: ../../../../src/silx/resources/gui/icons/add-shape-vertical.png .. |add| image:: ../../../../src/silx/resources/gui/icons/add.png @@ -554,6 +561,8 @@ Available icons .. |rm| image:: ../../../../src/silx/resources/gui/icons/rm.png .. |rotate-3d| image:: ../../../../src/silx/resources/gui/icons/rotate-3d.png .. |rudder| image:: ../../../../src/silx/resources/gui/icons/rudder.png +.. |scale-auto| image:: ../../../../src/silx/resources/gui/icons/scale-auto.png +.. |scale-fixed| image:: ../../../../src/silx/resources/gui/icons/scale-fixed.png .. |selected| image:: ../../../../src/silx/resources/gui/icons/selected.png .. |shape-circle-solid| image:: ../../../../src/silx/resources/gui/icons/shape-circle-solid.png .. |shape-circle| image:: ../../../../src/silx/resources/gui/icons/shape-circle.png diff --git a/doc/source/modules/gui/plot/getting_started.rst b/doc/source/modules/gui/plot/getting_started.rst index 1c29f23..f8d80ec 100644 --- a/doc/source/modules/gui/plot/getting_started.rst +++ b/doc/source/modules/gui/plot/getting_started.rst @@ -89,7 +89,7 @@ A Qt GUI script must have a QApplication initialised before creating widgets: [...] qapp.exec() -Unless a Qt binding has already been loaded, :mod:`silx.gui.qt` uses one of the supported Qt bindings (PyQt5, PySide2, PySide6). +Unless a Qt binding has already been loaded, :mod:`silx.gui.qt` uses one of the supported Qt bindings (PyQt5, PySide6, PyQt6). If you prefer to choose the Qt binding yourself, import it before importing a module from :mod:`silx.gui`: diff --git a/doc/source/modules/gui/plot/img/BasicGridStatsWidget.png b/doc/source/modules/gui/plot/img/BasicGridStatsWidget.png Binary files differindex 261909a..a468cc1 100644 --- a/doc/source/modules/gui/plot/img/BasicGridStatsWidget.png +++ b/doc/source/modules/gui/plot/img/BasicGridStatsWidget.png diff --git a/doc/source/modules/gui/plot/img/BasicStatsWidget.png b/doc/source/modules/gui/plot/img/BasicStatsWidget.png Binary files differindex b0d815d..6dbdd30 100644 --- a/doc/source/modules/gui/plot/img/BasicStatsWidget.png +++ b/doc/source/modules/gui/plot/img/BasicStatsWidget.png diff --git a/doc/source/modules/gui/plot/img/LimitsToolBar.png b/doc/source/modules/gui/plot/img/LimitsToolBar.png Binary files differindex b360fe0..2d96458 100644 --- a/doc/source/modules/gui/plot/img/LimitsToolBar.png +++ b/doc/source/modules/gui/plot/img/LimitsToolBar.png diff --git a/doc/source/modules/gui/plot/img/ROIStatsWidget.png b/doc/source/modules/gui/plot/img/ROIStatsWidget.png Binary files differindex 7a634fe..fae9d62 100644 --- a/doc/source/modules/gui/plot/img/ROIStatsWidget.png +++ b/doc/source/modules/gui/plot/img/ROIStatsWidget.png diff --git a/doc/source/modules/gui/plot/img/logColorbar.png b/doc/source/modules/gui/plot/img/logColorbar.png Binary files differindex 49282e7..31594e0 100644 --- a/doc/source/modules/gui/plot/img/logColorbar.png +++ b/doc/source/modules/gui/plot/img/logColorbar.png diff --git a/doc/source/modules/gui/plot3d/img/SceneWidget.png b/doc/source/modules/gui/plot3d/img/SceneWidget.png Binary files differindex 4ddc0a8..7ad6de4 100644 --- a/doc/source/modules/gui/plot3d/img/SceneWidget.png +++ b/doc/source/modules/gui/plot3d/img/SceneWidget.png diff --git a/doc/source/modules/gui/widgets/img/FrameBrowser.png b/doc/source/modules/gui/widgets/img/FrameBrowser.png Binary files differindex 1d4ebcf..6f46631 100644 --- a/doc/source/modules/gui/widgets/img/FrameBrowser.png +++ b/doc/source/modules/gui/widgets/img/FrameBrowser.png diff --git a/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png b/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png Binary files differindex 96edd3c..13a4ddf 100644 --- a/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png +++ b/doc/source/modules/gui/widgets/img/HorizontalSliderWithBrowser.png diff --git a/doc/source/modules/gui/widgets/img/PeriodicCombo.png b/doc/source/modules/gui/widgets/img/PeriodicCombo.png Binary files differindex 7534805..bec3a78 100644 --- a/doc/source/modules/gui/widgets/img/PeriodicCombo.png +++ b/doc/source/modules/gui/widgets/img/PeriodicCombo.png diff --git a/doc/source/modules/gui/widgets/img/PeriodicList.png b/doc/source/modules/gui/widgets/img/PeriodicList.png Binary files differindex 74ce7d6..a695525 100644 --- a/doc/source/modules/gui/widgets/img/PeriodicList.png +++ b/doc/source/modules/gui/widgets/img/PeriodicList.png diff --git a/doc/source/modules/gui/widgets/img/PeriodicTable.png b/doc/source/modules/gui/widgets/img/PeriodicTable.png Binary files differindex bada39a..70039ab 100644 --- a/doc/source/modules/gui/widgets/img/PeriodicTable.png +++ b/doc/source/modules/gui/widgets/img/PeriodicTable.png diff --git a/doc/source/modules/gui/widgets/img/RangeSlider.png b/doc/source/modules/gui/widgets/img/RangeSlider.png Binary files differindex e7a1011..f552fb3 100644 --- a/doc/source/modules/gui/widgets/img/RangeSlider.png +++ b/doc/source/modules/gui/widgets/img/RangeSlider.png diff --git a/doc/source/modules/gui/widgets/img/TableWidget.png b/doc/source/modules/gui/widgets/img/TableWidget.png Binary files differindex a614ae7..959af57 100644 --- a/doc/source/modules/gui/widgets/img/TableWidget.png +++ b/doc/source/modules/gui/widgets/img/TableWidget.png diff --git a/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png b/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png Binary files differindex eb55b14..5d1af4c 100644 --- a/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png +++ b/doc/source/modules/gui/widgets/img/ThreadPoolPushButton.png diff --git a/doc/source/modules/gui/widgets/img/WaitingPushButton.png b/doc/source/modules/gui/widgets/img/WaitingPushButton.png Binary files differindex 97bd14a..5bfcdb8 100644 --- a/doc/source/modules/gui/widgets/img/WaitingPushButton.png +++ b/doc/source/modules/gui/widgets/img/WaitingPushButton.png diff --git a/doc/source/modules/io/commonh5.rst b/doc/source/modules/io/commonh5.rst new file mode 100644 index 0000000..9e62ccd --- /dev/null +++ b/doc/source/modules/io/commonh5.rst @@ -0,0 +1,28 @@ +. currentmodule:: silx.io + +:mod:`commonh5`: Helpers for writing h5py-like API +-------------------------------------------------- + +.. automodule:: silx.io.commonh5 + +Classes ++++++++ + +.. autoclass:: Node + :members: + +.. autoclass:: File + :show-inheritance: + :members: + +.. autoclass:: Group + :show-inheritance: + :undoc-members: + :members: name, basename, file, attrs, h5py_class, parent, + get, keys, values, items, visit, visititems + :special-members: __getitem__, __len__, __contains__, __iter__ + :exclude-members: add_node + +.. autoclass:: Dataset + :show-inheritance: + :members: diff --git a/doc/source/modules/io/fioh5.rst b/doc/source/modules/io/fioh5.rst index c901878..99498de 100644 --- a/doc/source/modules/io/fioh5.rst +++ b/doc/source/modules/io/fioh5.rst @@ -24,12 +24,4 @@ Classes .. autoclass:: FioFile -.. autoclass:: silx.io.commonh5.Group - :show-inheritance: - :undoc-members: - :members: name, basename, file, attrs, h5py_class, parent, - get, keys, values, items, visit, visititems - :special-members: __getitem__, __len__, __contains__, __iter__ - :exclude-members: add_node - .. autofunction:: is_fiofile
\ No newline at end of file diff --git a/doc/source/modules/io/index.rst b/doc/source/modules/io/index.rst index a511bef..b69a760 100644 --- a/doc/source/modules/io/index.rst +++ b/doc/source/modules/io/index.rst @@ -7,7 +7,8 @@ .. toctree:: :maxdepth: 1 - + + commonh5.rst configdict.rst convert.rst dictdump.rst diff --git a/doc/source/modules/io/spech5.rst b/doc/source/modules/io/spech5.rst index 61e0083..a9b8456 100644 --- a/doc/source/modules/io/spech5.rst +++ b/doc/source/modules/io/spech5.rst @@ -26,14 +26,6 @@ Classes .. autoclass:: SpecH5Group :show-inheritance: -.. autoclass:: silx.io.commonh5.Group - :show-inheritance: - :undoc-members: - :members: name, basename, file, attrs, h5py_class, parent, - get, keys, values, items, visit, visititems - :special-members: __getitem__, __len__, __contains__, __iter__ - :exclude-members: add_node - .. autoclass:: SpecH5Dataset :show-inheritance: diff --git a/doc/source/overview.rst b/doc/source/overview.rst index e65c163..729bdec 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -8,16 +8,21 @@ Source code, pre-built binaries (aka Python wheels) for Windows, MacOS and ManyLinux, Debian/Ubuntu packages of released versions are made available in the following places: - `Wheels and source code on PyPi <https://pypi.org/project/silx/>`_ +- `Conda package on conda-forge channel <https://anaconda.org/conda-forge/silx>`_ +- Windows application installer `on github release page <https://github.com/silx-kit/silx/releases/latest/>`_ (available in the `Assets` at the bottom). - `Documentation on silx.org <http://www.silx.org/doc/silx/latest/>`_ -- `Unofficial Debian/Ubuntu packages <https://github.com/silx-kit/silx/releases>`_ +- `Unofficial Debian/Ubuntu packages <https://github.com/silx-kit/silx/releases/latest>`_ - :doc:`changelog` +|release| |version| + Nightly builds -------------- Linux packages and documentation are automatically generated from the tip of the project's repository on a regular basis: - `Debian 10 and Ubuntu20.04 packages <http://www.silx.org/pub/linux-repo/>`_ +- `Wheels and Windows application <https://silx.gitlab-pages.esrf.fr/bob/silx/>`_ - `Documentation <http://www.silx.org/doc/silx/dev/>`_ Project diff --git a/doc/source/sample_code/img/plotUpdateImageFromGevent.png b/doc/source/sample_code/img/plotUpdateImageFromGevent.png Binary files differnew file mode 100644 index 0000000..c0caec3 --- /dev/null +++ b/doc/source/sample_code/img/plotUpdateImageFromGevent.png diff --git a/doc/source/sample_code/index.rst b/doc/source/sample_code/index.rst index 0aade4c..c33d560 100644 --- a/doc/source/sample_code/index.rst +++ b/doc/source/sample_code/index.rst @@ -343,6 +343,10 @@ Sample code that illustrates some functionalities of :class:`~silx.gui.plot.Plot In this example a thread calls submitToQtMainThread to update the curve of a plot. + * - :download:`plotUpdateImageFromGevent.py <../../../examples/plotUpdateImageFromGevent.py>` + - .. image:: img/plotUpdateImageFromGevent.png + :width: 150px + - This script illustrates the update of a :class:`~silx.gui.plot.Plot2D` widget from a gevent coroutine. * - :download:`plotUpdateImageFromThread.py <../../../examples/plotUpdateImageFromThread.py>` - .. image:: img/plotUpdateImageFromThread.png :width: 150px diff --git a/doc/source/virtualenv.rst b/doc/source/virtualenv.rst index 280c031..537336d 100644 --- a/doc/source/virtualenv.rst +++ b/doc/source/virtualenv.rst @@ -132,7 +132,7 @@ To test *silx*, open an interactive python console: python -If you don't have PyQt5, PySide2 or PySide6, run: +If you don't have PyQt5, PySide6 or PyQt6, run: .. code-block:: bash |
