Merge pull request #4326 from t20100/update-contributing-doc

Documentation: Updated contribution guidelines

Author: t20100

CONTRIBUTING.rst

@@ -10,30 +10,23 @@ which is described in other projects like `scikit-image <https://scikit-image.or
 
 1. Create your `GitHub <https://github.com/>`_ account and upload your SSH keys.
 
-2. Fork the silx project from https://github.com/silx-kit/silx/.
+2. `Fork the silx project <https://github.com/silx-kit/silx/fork>`_.
 
-3. Clone your GitHub repository on yout local computer.
+3. Clone your GitHub repository on your local computer:
 
-.. code-block:: bash
+   .. code-block:: bash
 
-   git clone [email protected]/<your_user_name>/silx
-   cd silx
+      git clone [email protected]:<your_user_name>/silx
+      cd silx
 
-4. Install the dependencies defined in *requirements-dev.txt*.
+4. `Install silx for development`_.
 
-.. code-block:: bash
-
-   pip install -r requirements-dev.txt
-
-5. Make sure the silx test suite pass on your computer using the ``python3 run_tests.py`` or
-   ``python3 run_tests.py silx.gui.test.test_qt`` if you want to test only a subset of it. 
-   You can use ``python /path/to/silx/bootstrap.py script.py`` to test your scripts without
-   installing silx, but the test suite is required to pass.
+5. `Run the tests`_ to make sure the silx test suite pass on your computer.
 
 6. Open an issue in ``https://github.com/silx-kit/silx/issues`` to inform the
    maintainers of your intentions.
 
-7. Create a local branch to start working on your issue ``git branch my_feature``.
+7. Create a local branch to start working on your issue: ``git branch my_feature``.
 
 8. Code, enjoy but ensure that the new code is tested and does not break
    the current test suite.
@@ -49,52 +42,40 @@ which is described in other projects like `scikit-image <https://scikit-image.or
 If you encounter any problems or have any questions you can always ask on the `Issues page <https://github.com/silx-kit/silx/issues>`_.
 
 
-Pull Request title format
--------------------------
+Install silx for development
+----------------------------
 
-To ease release notes authoring, when creating a Pull Request (PR), please use the following syntax for the title::
+1. Install `build dependencies <https://mesonbuild.com/meson-python/how-to-guides/editable-installs.html#build-dependencies>`_::
 
-  <Subpackage/Module/Topic>: <Action> <summary of the main change affecting silx's users>
+      pip install meson-python ninja cython
 
+2. Install silx in `editable mode <https://peps.python.org/pep-0660/>`_ with the development dependencies::
 
-With:
+      pip install --no-build-isolation --editable .[dev]
 
-- **Subpackage/Topic**: One of:
+.. note::
 
-  - A subpackage or a module: Use the fully qualified name of the subpackage or module of silx the PR is changing.
-    For example: ``silx.gui.qt`` or ``silx.gui.plot.PlotWidget``.
-  - A topic: If changes do not affect a particular subpackage or module, provide the topic of the change.
-    This can be for example: ``Build``, ``Documentation``, ``CI``,... or the name of a silx application (e.g., ``silx view``).
+    If the project "entry points" are modified, the project must be re-installed.
 
-- **Action**: How the changes affects the project from a silx user point of view.
-  Prefer using one of the following actions:
+.. seealso::
 
-  - **Added**: For new feature or new APIs
-  - **Deprecated**
-  - **Removed**
-  - **Changed**
-  - **Improved**
-  - **Refactored**
-  - **Fixed**
-  - More: If none of the previous actions match your changes, please use another keyword.
+    `Meson editable installs <https://mesonbuild.com/meson-python/how-to-guides/editable-installs.html>`_
 
-- **Summary**: A short description of the main change as you would like to read it from release notes.
 
-
-Code formatting
+Format the code
 ---------------
 
-To format the code, use `black <https://black.readthedocs.io>`_.
+To format the code, use `black <https://black.readthedocs.io>`_::
 
+    black .
 
-How-to build the documentation
-------------------------------
 
-To build the documentation, using  `Sphinx <http://www.sphinx-doc.org/>`_, run:
+Build the documentation
+-----------------------
 
-.. code-block:: bash
+- `Install silx for development`_.
+- From the silx project root folder, run `Sphinx <http://www.sphinx-doc.org/>`_::
 
-    pip install .  # Make sure to install the same version as the source
     sphinx-build doc/source/ build/html
 
 .. note::
@@ -103,22 +84,64 @@ To build the documentation, using  `Sphinx <http://www.sphinx-doc.org/>`_, run:
     environment variable ``DIRECTIVE_SNAPSHOT_QT`` set to ``True``.
 
 
-How-to run the tests
---------------------
+Run the tests
+-------------
+
+- `Install silx for development`_.
+- From the silx project root folder, use `pytest <https://docs.pytest.org/en/stable/how-to/usage.html>`_:
+
+.. warning::
+     
+     GUI tests are part of the complete test suite and will make windows appear and disappear very quickly.
+     
+      **Do not run these if you have a history of epilepsy or motion sickness** 
+      
+  * To run the complete test suite::
+
+      pytest
+
+  * To run a specfic test::
+
+      pytest <src/silx/path/to/test_file.py>  # or
+      pytest --pyargs <silx.subpackage.test.test_module>
 
-To run the tests of an installed version of *silx*, run the following on the python interpreter:
+To run the tests of an installed version of *silx*, run the following from 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
+Pull Request title format
+-------------------------
+
+To ease release notes authoring, when creating a Pull Request (PR), please use the following syntax for the title::
+
+  <Subpackage/Module/Topic>: <Action> <summary of the main change affecting silx's users>
+
+
+With:
+
+- **Subpackage/Topic**: One of:
+
+  - A subpackage or a module: Use the fully qualified name of the subpackage or module of silx the PR is changing.
+    For example: ``silx.gui.qt`` or ``silx.gui.plot.PlotWidget``.
+  - A topic: If changes do not affect a particular subpackage or module, provide the topic of the change.
+    This can be for example: ``Build``, ``Documentation``, ``CI``,... or the name of a silx application (e.g., ``silx view``).
+
+- **Action**: How the changes affect the project from a silx user point of view.
+  Prefer using one of the following actions:
+
+  - **Added**: For new feature or new APIs
+  - **Deprecated**
+  - **Removed**
+  - **Changed**
+  - **Improved**
+  - **Refactored**
+  - **Fixed**
 
-     python ./run_tests.py
+- **Summary**: A short description of the main change that will be included in the release notes.
 
 
 How-to make a release

MANIFEST.in

@@ -158,12 +158,9 @@ The GUI widgets depend on the following extra packages:
 * `pyopencl <https://mathema.tician.de/software/pyopencl/>`_
 * `Mako <http://www.makotemplates.org/>`_
 
-List of dependencies with minimum required versions:
-
-.. include:: ../../requirements.txt
-   :literal:
 
 Build dependencies
 ++++++++++++++++++
 
-In addition to run-time dependencies, building *silx* requires a C/C++ compiler and `cython <http://cython.org>`_.
+*silx* uses `meson-python <https://mesonbuild.com/meson-python/>`_ build backend and
+requires `cython <http://cython.org>`_ and a C/C++ compiler.

doc/source/install.rst

@@ -5,7 +5,7 @@ Pre-requisites
 --------------
 
 - `PyInstaller <https://pyinstaller.readthedocs.io/>`_ must be installed.
-  Run: ``pip install -r requirements-dev.txt``
+  Run: ``pip install pyinstaller``
 - `InnoSetup <https://jrsoftware.org/isinfo.php>`_ must be installed and in the ``PATH``.
 - silx and all its dependencies must be INSTALLED::
 

package/windows/README.rst

@@ -809,8 +809,6 @@ def printState(self):
 
         Can be used to add or regenerate `STATE_VERSION1_QT4` or
         `STATE_VERSION1_QT5`.
-
-        >>> ./run_tests.py -v silx.gui.dialog.test.test_datafiledialog.TestDataFileDialogApi.printState
         """
         dialog = self.createDialog()
         dialog.setDirectory("")

requirements-dev.txt

@@ -625,8 +625,6 @@ def printState(self):
 
         Can be used to add or regenerate `STATE_VERSION1_QT4` or
         `STATE_VERSION1_QT5`.
-
-        >>> ./run_tests.py -v silx.gui.dialog.test.test_imagefiledialog.TestImageFileDialogApi.printState
         """
         dialog = self.createDialog()
         colormap = Colormap(normalization=Colormap.LOGARITHM)

requirements.txt

@@ -53,8 +53,7 @@ class TestDebug(unittest.TestCase):
 
     def logB(self):
         """
-        Can be used to check the log output using:
-        `./run_tests.py silx.utils.test.test_debug.TestDebug.logB -v`
+        Can be used to check the log output
         """
         print()
         test = _Foobar()