DOC: update installation instructions for uv

CONTRIBUTING.rst

@@ -6,48 +6,68 @@ please create an issue or a pull request at
 https://github.com/spatialaudio/jackclient-python.
 Contributions are always welcome!
 
-Instead of pip-installing the latest release from PyPI, you should get the
-newest development version from Github_::
+Instead of installing the latest release from PyPI_, you should get the
+newest development version from GitHub_::
 
    git clone https://github.com/spatialaudio/jackclient-python.git
    cd jackclient-python
-   python -m pip install -e .
-   python jack_build.py
+   uv sync
+   uv run jack_build.py
 
-... where ``-e`` stands for ``--editable``.
 This way, your installation always stays up-to-date, even if you pull new
-changes from the Github repository.
+changes from the GitHub repository.
 
-.. _Github: https://github.com/spatialaudio/jackclient-python/
+.. _PyPI: https://pypi.org/project/JACK-Client/
+.. _GitHub: https://github.com/spatialaudio/jackclient-python/
 
 .. note::
 
    Whenever the file ``jack_build.py`` changes (either because you edited it or
-   it was updated by pulling from Github or switching branches), you have to
+   it was updated by pulling from GitHub or switching branches), you have to
    run the last command again.
 
-If you make changes to the documentation, you can locally re-create the HTML
-pages using Sphinx_.
-You can install it and a few other necessary packages with::
 
-   python -m pip install -r doc/requirements.txt
+Building the Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To create the HTML pages, use::
+If you make changes to the documentation,
+you can locally re-create the HTML pages using Sphinx_
+(which will be automatically installed as part of the development dependencies).
+From the main ``jackclient-python`` directory, run::
 
-   python -m sphinx doc _build
+   uv run sphinx-build doc _build
 
 The generated files will be available in the directory ``_build/``.
 
 .. _Sphinx: https://www.sphinx-doc.org/
 
-There are no proper tests (yet?), but the code examples from the README file
-can be verified with pytest_.
-If you haven't installed it already, you can install it with::
+While working on the documentation, it might be helpful to re-run Sphinx
+whenever something changes.  This can be done with::
 
-   python -m pip install pytest
+    uv run --with sphinx-autobuild sphinx-autobuild doc _build
 
-As soon as pytest_ is installed, you can run the (rudimentary) tests with::
+Running the Tests
+^^^^^^^^^^^^^^^^^
 
-   python -m pytest
+There are no proper tests (yet?), but the code examples in the documentation
+can be verified with pytest_ (which is also part of the development dependencies).
+You can run the (rudimentary) tests with::
+
+   uv run python -m pytest
 
 .. _pytest: https://pytest.org/
+
+
+Editable Installation
+^^^^^^^^^^^^^^^^^^^^^
+
+If you want to work in a different directory on your own files,
+but using the latest development version (or a custom branch) of
+the ``jack`` module, you can switch to a directory of your choice
+and enter this::
+
+   uv init --bare
+   uv add --editable --no-workspace path/to/your/jackclient-python/repo
+
+You can install further packages with ``uv add`` and then run
+whatever you need with ``uv run``.

README.rst

@@ -3,6 +3,13 @@ JACK Audio Connection Kit (JACK) Client for Python
 
 This Python module (named ``jack``) provides bindings for the JACK_ library.
 
+Quick Start:
+    #. Install JACK, Python and (optionally) NumPy
+
+    #. Install the ``JACK-Client`` package for Python
+
+    #. Try the examples shown in the documentation
+
 Documentation:
    https://jackclient-python.readthedocs.io/
 

doc/installation.rst

@@ -1,84 +1,78 @@
 Installation
 ============
 
-.. image:: https://badge.fury.io/py/JACK-Client.svg
-   :target: https://pypi.org/project/JACK-Client/
+Requirements
+------------
 
-You can use ``pip`` to install the ``jack`` module::
+The JACK_ library must be installed on your system (and CFFI must be able
+to find it).  You should use your package manager to install it.
+Make sure you install the JACK daemon (called ``jackd``). This will also
+install the JACK library package.
+If you don't have a package manager, you can try one of the binary installers
+from the `JACK download page`_.
+If you prefer, you can of course also download the sources and compile
+everything locally.
 
-   python -m pip install JACK-Client
+You'll also need to install Python_ if you haven't yet done so.
+There are many ways to install Python,
+and you can use any way you like,
+however, we recommend using uv_ as shown in the steps below.
 
-Depending on your Python installation (see `Requirements`_ below),
-you may have to use ``python3`` instead of ``python``.
-If you have installed the module already, you can use the ``--upgrade`` flag to
-get the newest release.
+You can install ``uv`` with your favorite package manager,
+or by one of the other methods described at
+https://docs.astral.sh/uv/getting-started/installation/.
 
-To un-install, use::
+If you don't like ``uv``, no problem!
+You can also use Python's official packaging tool pip_ or any other third-party tool,
+as long as it can install `the JACK-Client package`_.
 
-   python -m pip uninstall JACK-Client
+.. _JACK: https://jackaudio.org/
+.. _JACK download page: https://jackaudio.org/downloads/
+.. _Python: https://www.python.org/
+.. _uv: https://docs.astral.sh/uv/
+.. _pip: https://packaging.python.org/en/latest/tutorials/installing-packages/
+.. _the JACK-Client package: https://pypi.org/project/JACK-Client/
+.. _NumPy: http://www.numpy.org/
 
-Requirements
+
+Installation
 ------------
 
-You'll need some software packages in order to install and use the ``jack``
-module.  Some of those might already be installed on your system and some are
-automatically installed when you use the aforementioned ``pip`` command.
-
-Python:
-   Of course, you'll need Python_.  More specifically, you'll need Python 3.
-   If you don't have Python installed yet, you should get one of the
-   distributions which already include CFFI and NumPy (and many other useful
-   things), e.g. Anaconda_ or WinPython_.
-
-pip/setuptools:
-   Those are needed for the installation of the Python module and its
-   dependencies.  Most systems will have these installed already, but if not,
-   you should install it with your package manager or you can download and
-   install ``pip`` and ``setuptools`` as described on the `pip installation`_
-   page.
-   If you happen to have ``pip`` but not ``setuptools``, use this command::
-
-      python -m pip install setuptools
-
-   To upgrade to a newer version of an already installed package (including
-   ``pip`` itself), use the ``--upgrade`` flag.
-
-CFFI:
-   The `C Foreign Function Interface for Python`_ is used to access the C-API
-   of the JACK library from within Python.  It is supported on CPython
-   and is distributed with PyPy_.  It will be automatically installed
-   when installing the ``JACK-Client`` package with ``pip``.
-   If you prefer, you can also install it with your package
-   manager (the package might be called ``python3-cffi`` or similar).
-
-JACK library:
-   The JACK_ library must be installed on your system (and CFFI must be able
-   to find it).  Again, you should use your package manager to install it.
-   Make sure you install the JACK daemon (called ``jackd``). This will also
-   install the JACK library package.
-   If you don't have a package manager, you can try one of the binary installers
-   from the `JACK download page`_.
-   If you prefer, you can of course also download the sources and compile
-   everything locally.
-
-NumPy (optional):
-   NumPy_ is only needed if you want to access the input and output buffers in
-   the process callback as NumPy arrays.
-   The only place where NumPy is needed is `jack.OwnPort.get_array()`
-   (and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative).
-   If you need NumPy, you can install it with your package manager or use a
-   Python distribution that already includes NumPy (see above).
-   You can also install NumPy with ``pip``, but depending on your platform, this
-   might require a compiler and several additional libraries::
-
-      python -m pip install NumPy
+First, create a new directory wherever you want, change into it, then run::
 
-.. _JACK: https://jackaudio.org/
-.. _NumPy: https://numpy.org/
-.. _Python: https://www.python.org/
-.. _Anaconda: https://www.anaconda.com/download/success
-.. _WinPython: http://winpython.github.io/
-.. _C Foreign Function Interface for Python: https://cffi.readthedocs.org/
-.. _PyPy: https://www.pypy.org/
-.. _JACK download page: https://jackaudio.org/downloads/
-.. _pip installation: https://pip.pypa.io/en/latest/installing/
+    uv init --bare
+
+This will create a file named ``pyproject.toml`` for you.
+Use the ``--help`` flag to see other options.
+
+The ``jack`` module can now be installed with::
+
+    uv add JACK-Client
+
+This will also create a file named ``uv.lock``, which tracks the exact versions
+of all installed packages.
+
+NumPy_ is only needed if you want to access the input and output buffers in
+the process callback as NumPy arrays.
+The only place where NumPy is needed is `jack.OwnPort.get_array()`
+(and you can use `jack.OwnPort.get_buffer()` as a NumPy-less alternative).
+If you need NumPy, you can install it with::
+
+    uv add numpy
+
+Similarly, you can install other Python-related tools::
+
+    uv add ...
+
+Once everything is installed, you can start working with the editor/IDE/tool
+of your choice by simply prefixing it with ``uv run``, for example::
+
+    uv run python
+
+If you have a Python script (for inspiration see :doc:`examples`),
+e.g. ``my_script.py``, you can run it with::
+
+    uv run my_script.py
+
+If you want to install the latest development version of the JACK-Client,
+have a look at :doc:`contributing`.