diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 20633fe4de..3d545e7176 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,9 +1,4 @@ - + Checklist: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0eb16e2a07..5fcf8b795e 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,23 +1,23 @@ -How to contribute to *silx* -=========================== +How to contribute +================= -This document describes how to contribute to the *silx* project. -The process is similar to many other open-source projects like *numpy*, just lighter as the project is smaller, so you won't be surprised with the pipeline. -*scikit-image* provides a nice tutorial in `their own CONTRIBUTING guide`_. +Development process +------------------- +This project follows the standard open-source project github workflow, +which is described in other projects like `scikit-image `_. -1. Create your GitHub account `https://help.github.com/categories/setup/` - and upload your SSH keys. +1. Create your `GitHub `_ account and upload your SSH keys. -2. Fork the silx project from `https://github.com/silx-kit/silx/`. - The button is on the top right of the page. +2. Fork the silx project from https://github.com/silx-kit/silx/. -3. Clone your GitHub version locally on the computer you intend to work on. +3. Clone your GitHub repository on yout local computer. .. code-block:: bash git clone git@github.com//silx + cd silx 4. Install the dependencies defined in *requirements-dev.txt*. @@ -42,16 +42,17 @@ The process is similar to many other open-source projects like *numpy*, just lig 10. Create a pull request (PR) from your feature branch on GitHub to trigger the review process. Indicate this PR is related to the issue you opened in 6. + Make sure to follow the `Pull Request title format`_. 11. Discuss with the maintainer who is reviewing your code using the GitHub interface. -If you encounter any problems or have any questions you can always ask on the `Issues page`_. +If you encounter any problems or have any questions you can always ask on the `Issues page `_. Pull Request title format ------------------------- -To ease release notes authoring, please use the following syntax for the title of your Pull Requests (PR):: +To ease release notes authoring, when creating a Pull Request (PR), please use the following syntax for the title:: : @@ -79,8 +80,46 @@ With: - **Summary**: A short description of the main change as you would like to read it from release notes. -.. _their own CONTRIBUTING guide: https://github.com/scikit-image/scikit-image/blob/3736339272b9d129f98fc723b508ac5490c171fa/CONTRIBUTING.rst -.. _Issues page: https://github.com/silx-kit/silx/issues + +Code formatting +--------------- + +To format the code, use `black `_. + + +How-to build the documentation +------------------------------ + +To build the documentation, using `Sphinx `_, run: + +.. code-block:: bash + + 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``. + + +How-to run the tests +-------------------- + +To run the tests of an installed version of *silx*, run the following on the python interpreter: + +.. code-block:: python + + import silx.test + silx.test.run_tests() + +To run the test suite of a development version, use the *run_tests.py* script at +the root of the source project. + +.. code-block:: bash + + python ./run_tests.py + How-to make a release --------------------- diff --git a/README.rst b/README.rst index 7ab537c928..af3b2f2ede 100644 --- a/README.rst +++ b/README.rst @@ -99,8 +99,8 @@ License ------- The source code of *silx* is licensed under the MIT license. -See the `LICENSE `_ and -`copyright `_ files for details. +See the `LICENSE `_ and +`copyright `_ files for details. Citation -------- diff --git a/doc/source/applications/view.rst b/doc/source/applications/view.rst index a12516d8fa..e4bb39b7bf 100644 --- a/doc/source/applications/view.rst +++ b/doc/source/applications/view.rst @@ -51,8 +51,8 @@ Custom plot selection Plot custom curves from selected 1D datasets. -How to access : -............ +How to access +............. .. grid :: 1 2 2 2 diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000000..ac7b6bcf35 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index aa28f7e434..c794464af7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -29,20 +29,28 @@ You can install **silx** via `pip `_, `conda `_ -- `h5py `_ -- `fabio `_ - -The GUI widgets depend on the following extra packages: - -* A Qt binding: either `PyQt5 `_, - `PySide6 `_ or - `PyQt6 `_ -* `matplotlib `_ -* `PyOpenGL `_ -* `qt_console `_ - for the ``silx.gui.console`` widget. -* `dateutil `_ - -*silx.opencl* further depends on OpenCL and the following packages too : +.. _Installation with conda: -* `pyopencl `_ -* `Mako `_ +Installation with conda +----------------------- -The complete list of dependencies with the minimal version is described in the -`requirement.txt `_ -at the top level of the source package. - -Build dependencies -++++++++++++++++++ +To install silx and all its dependencies_, run: -In addition to run-time dependencies, building *silx* requires a C/C++ compiler, -`numpy `_ and `cython `_. - -The complete list of dependencies for building the package, including its -documentation, is described in the -`requirement-dev.txt `_ -at the top level of the source package. - - -Linux ------ +.. code-block:: bash -Packages are available for a few distributions: + conda install -c conda-forge silx -- Debian/Ubuntu: see `Installing a Debian package`_. -- `CentOS 7 RPM packages `_ provided by the Max IV institute at Lund, Sweden. -- `Fedora 23 rpm packages `_ provided by the Max IV institute at Lund, Sweden. -- `Arch Linux (AUR) package `_ provided by Leonid Bloch. +To install silx with a minimal set of dependencies, run: -You can also follow one of those installation procedures: +.. code-block:: bash -- `Installing with pip`_ -- Installing in a `Virtual Environment`_ -- `Installing from source`_ + conda install -c conda-forge silx-base +.. _Installation on Debian & Ubuntu: -Installing a Debian package -+++++++++++++++++++++++++++ +Installation on Debian & Ubuntu +------------------------------- -silx is officially packaged in `Debian `_ +silx is packaged in `Debian `_ and `Ubuntu `_. -To install it, run `apt-get install silx` as root. -The `python3-silx` package provides the library, while the `silx` package provides the executable (`silx view`, `silx convert`, ...). - -Unofficial (possibly more recent) packages are available for Debian 10 (Buster, amd64) and Ubuntu 20.04 (Focal, amd64 and ppc64le) in this repository: http://www.silx.org/pub/linux-repo/. -See information on `how-to use this repository `_ before running `apt-get install silx`. - -.. note:: - - Those packages are built automatically, hence not signed. - You have to accept the installation of non-signed packages. - -If the packages are not installed, it might be due to the priority list. -You can display the priority list using `apt-cache policy silx`. -If the Pin-number of silx.org is too low compared to other sources, -see the "Information/Troubleshooting" section `here `_, -and start the update/install procedure again. - - -Windows -------- - -The simplest way of installing *silx* on Windows is to install it with ``pip``, see `Installing with pip`_:: - - pip install silx[full] - -This assumes you have Python and pip installed and configured. -If you don't, read the following sections. - -Alternatively, you can check: - -- Installing in a `Virtual Environment`_ -- `Installing from source`_ - -Installing Python -+++++++++++++++++ - -Download and install Python from `python.org `_. - -We recommend that you install the 64bit version of Python, which is not the -default version suggested on the Python website. -The 32bit version has limited memory, and also we don't provide a -binary wheel for it. -This means that you would have to install *silx* from its sources, which requires -you to install a C compiler first. - -Configure Python as explained on -`docs.python.org `_ -to add the python installation directory to your PATH environment variable. - -Alternative Scientific Python stacks exists such as -`WinPython `_ or `Anaconda `_. -They all offer most of the scientific packages already installed which makes the -installation of dependencies much easier. - -Using pip -+++++++++ - -Configure your PATH environment variable to include the pip installation -directory, the same way as described for Python. - -The pip installation directory will likely be ``C:\Python35\Scripts\``. - -Then you will be able to use all the pip commands listed below in a command -prompt. - - -MacOS ------ - -Make sure to use python3 to install silx (you might need to install python3). - -Then, install *silx* with ``pip``, see `Installing with pip`_:: - - pip install silx[full] - -This should work without issues, as binary wheels of *silx* are provided on -PyPi. - - -Virtual Environment -------------------- - -Virtual environments are self-contained directory trees that contain a Python -installation for a particular version of Python, plus a number of additional -packages. -They do not require administrator privileges, nor *root* access. - -To create a virtual environment, decide upon a directory where you want to place -it (for example *myenv*), and run the *venv* module as a script with the directory path: +To install silx with the executable (`silx view`, `silx convert`, ...) and all its dependencies_, run: .. code-block:: bash - python3 -m venv myenv - -This will create the *myenv* directory if it doesn’t exist, and also create -directories inside it containing a copy of the Python interpreter, the standard -library, and various supporting files. - -Once you’ve created a virtual environment, you may activate it. + sudo apt-get install silx -On Windows, run: +To install the silx Python package with a minimal set of dependencies, run: .. code-block:: bash - myenv\\Scripts\\activate.bat + sudo apt-get install python3-silx -On Unix or MacOS, run: -.. code-block:: bash - - source myenv/bin/activate - -You can install, upgrade, and remove packages using a program called *pip* within -your virtual environment (see `Installing with pip`_). +Installation on Arch Linux +-------------------------- -.. code-block:: bash - - pip install silx[full] +silx is packaged in `Arch Linux (AUR) `_. -Installing from source ----------------------- +To install silx, run: -Building *silx* from the source requires some `Build dependencies`_ which may be -installed using: - -.. code-block:: bash - - pip install -r https://github.com/silx-kit/silx/raw/master/requirements-dev.txt +.. code-block:: bash + sudo pacman -S python-silx -Building from source -++++++++++++++++++++ -Source package of *silx* releases can be downloaded from -`the pypi project page `_. +Installation from source +------------------------ -After downloading the `silx-x.y.z.tar.gz` archive, extract its content:: +To install silx from source, run: - tar xzvf silx-x.y.z.tar.gz - -Alternatively, you can get the latest source code from the master branch of the -`git repository `_: https://github.com/silx-kit/silx +.. code-block:: bash -You can now build and install *silx* from its sources: + pip install silx --no-binary silx +.. warning:: -.. code-block:: bash + On MacOS, you might get the following error:: - cd silx-x.y.z - pip uninstall -y silx - pip install . [--user] + UnicodeDecodeError: 'ascii' codec can't decode byte 0xc2 in position 1335: ordinal not in range(128) -Known issues -............ + This is related to the two environment variables LC_ALL and LANG not being defined (or wrongly defined to UTF-9). + To set the environment variables, run: -There are specific issues related to MacOSX. If you get this error:: + .. code-block:: bash - UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 1335: ordinal not in range(128) + export LC_ALL=en_US.UTF-9 + export LANG=en_US.UTF-9 -This is related to the two environment variables LC_ALL and LANG not being defined (or wrongly defined to UTF-8). -To set the environment variables, type on the command line: +Build options can be set through environment variables, for example: -.. code-block:: bash +.. code-block:: - export LC_ALL=en_US.UTF-8 - export LANG=en_US.UTF-8 + SILX_WITH_OPENMP=False pip install silx --no-binary silx -Advanced build options -++++++++++++++++++++++ -Advanced options can be set through the following environment variables: +Build options ++++++++++++++ .. list-table:: :widths: 1 4 @@ -312,43 +130,40 @@ Advanced options can be set through the following environment variables: .. note:: Boolean options are passed as ``True`` or ``False``. -Package the build into a wheel and install it (this requires to install the `build `_ package): - -.. code-block:: bash - - python -m build --wheel - pip install dist/silx*.whl - -To build the documentation, using `Sphinx `_: +.. _dependencies: -.. code-block:: bash +Dependencies +------------ - pip install . # Make sure to install the same version as the source - sphinx-build doc/source/ build/html +The mandatory dependencies are: -.. note:: +- `fabio `_ +- `h5py `_ +- `numpy `_ +- `packaging `_ - To re-generate the example script screenshots, build the documentation with the - environment variable ``DIRECTIVE_SNAPSHOT_QT`` set to ``True``. +The GUI widgets depend on the following extra packages: -Formatting -++++++++++ +* A Qt binding: either `PyQt5 `_ (>= 5.9), + `PySide6 `_ (>= 6.4) or + `PyQt6 `_ (>= 6.3) +* `matplotlib `_ +* `PyOpenGL `_ +* `qtconsole `_ + for the ``silx.gui.console`` widget. +* `python-dateutil `_ -To format the code, use `black `_. +*silx.opencl* further depends on OpenCL and the following packages too : -Testing -+++++++ +* `pyopencl `_ +* `Mako `_ -To run the tests of an installed version of *silx*, run the following on the python interpreter: +List of dependencies with minimum required versions: -.. code-block:: python - - import silx.test - silx.test.run_tests() +.. include:: ../../requirements.txt + :literal: -To run the test suite of a development version, use the *run_tests.py* script at -the root of the source project. +Build dependencies +++++++++++++++++++ -.. code-block:: bash - - python ./run_tests.py +In addition to run-time dependencies, building *silx* requires a C/C++ compiler and `cython `_. diff --git a/doc/source/modules/gui/plot/dev.rst b/doc/source/modules/gui/plot/dev.rst index 0c848e984e..854a5aa9e1 100644 --- a/doc/source/modules/gui/plot/dev.rst +++ b/doc/source/modules/gui/plot/dev.rst @@ -77,14 +77,6 @@ The following modules are the modules used internally by the plot package. .. automodule:: silx.gui.plot.backends.BackendBase :members: -:mod:`backends.BackendMatplotlib` -+++++++++++++++++++++++++++++++++ - -.. currentmodule:: silx.gui.plot.backends.BackendMatplotlib - -.. automodule:: silx.gui.plot.backends.BackendMatplotlib - :members: - :mod:`CurvesROIWidget` ++++++++++++++++++++++ diff --git a/doc/source/user_guide.rst b/doc/source/user_guide.rst index 1af6bbe824..b9d394ecee 100644 --- a/doc/source/user_guide.rst +++ b/doc/source/user_guide.rst @@ -46,8 +46,8 @@ The current version (v\ |version|) caters for: install.rst description/index.rst license.rst - virtualenv.rst troubleshooting.rst + contributing.rst :doc:`overview` Releases, repository, issue tracker, mailing list, ... @@ -79,6 +79,9 @@ The current version (v\ |version|) caters for: :doc:`troubleshooting` When things do not work as expected +:doc:`contributing` + How to contribute to the *silx* project + Indices ======= diff --git a/doc/source/virtualenv.rst b/doc/source/virtualenv.rst deleted file mode 100644 index 6f64d5bd64..0000000000 --- a/doc/source/virtualenv.rst +++ /dev/null @@ -1,144 +0,0 @@ - -.. _silx-venv: - -Installing silx in a virtualenv -=============================== - -This step-by-step guide explains how to install *silx* in a virtualenv. - - -Prerequisites -------------- - -This guide assumes that your system meets the following requirements: - - - a version of python compatible with *silx* is installed - - the *pip* installer for python packages is installed - -Installation procedure ----------------------- - -Create a virtualenv -******************* - -The files required by a virtual environment are created in a new folder -with the same name as the virtualenv. So make sure you are in a directory -in which you have write permissions. - -In this tutorial we use a folder ``venvs`` in our home directory, and we create -a virtual environment named ``silx_venv`` - -.. code-block:: bash - - cd - mkdir -p venvs - cd venvs - python -m venv silx_venv - -A virtualenv contains a copy of your default python interpreter with a few tools -to install packages (pip, setuptools). - -Virtual environments are created using a builtin standard library, ``venv`` (Python3 only): - -.. code-block:: bash - - python3 -m venv /path/to/new/virtual/environment - -.. note:: - - On Debian platforms, you might need to install the ``python3-venv`` package. - - If you don't need to start with a clean environment and you don't want - to install each required library one by one, you can use a command line - option to create a virtualenv with access to all system packages: - ``--system-site-packages`` - -To use a different python interpreter, use it to create the virtual environment. -For example, to use python 3.10: - -.. code-block:: bash - - /usr/bin/python3.10 -m venv silx_venv - - -Activate a virtualenv -********************* - -A script is provided in your virtualenv to activate it. - -.. code-block:: bash - - source silx_venv/bin/activate - -After activating your new virtualenv, this python interpreter and its -package tools are used, instead of the ones from the system. - -Any libraries you will install or upgrade will be inside the virtual -environment, and will not affect the rest of system. - -To deactivate the virtual environment, just type ``deactivate``. - -Upgrade pip -*********** - -After activating *silx_venv*, you should upgrade *pip*: - -.. code-block:: bash - - python -m pip install --upgrade pip - - -Upgrade setuptools and wheel -**************************** - -Upgrading the python packaging related libraries can make installing the -rest of the libraries much easier. - -.. code-block:: bash - - pip install setuptools --upgrade - pip install wheel --upgrade - -Install build dependencies -************************** - -The following command installs libraries that are required to build and -install *silx*: - -.. code-block:: bash - - pip install numpy cython - -.. since 0.5, numpy is now automatically installed when doing `pip install silx` - -Install silx -************ - -To install silx with minimal dependencies, run: - -.. code-block:: bash - - pip install silx - -To install silx with all dependencies, run: - -.. code-block:: bash - - pip install silx[full] - -To test *silx*, open an interactive python console: - -.. code-block:: bash - - python - -If you don't have PyQt5, PySide6 or PyQt6, run: - -.. code-block:: bash - - WITH_QT_TEST=False python - -Run the test suite using: - - >>> import silx.test - >>> silx.test.run_tests()