Improve uv instructions, add dev dependencies (#187)

* Improve uv instructions, add dev dependencies

* Add --no-workspace to --editable

* Mention the example scripts

* Mention alternatives to uv

* RTD: use uv

* separate "test" and "doc" dependency groups

Author: mgeier

.github/workflows/test.yml

@@ -36,13 +36,9 @@ jobs:
     - name: Install dependencies
       run: |
         uv sync --locked
-        uv pip install -r tests/requirements.txt
-        uv pip install -r doc/requirements.txt
-        # This is needed in example scripts:
-        uv pip install pillow
     - name: Test
       run: uv run --locked -m pytest
     - name: Test examples
-      run: uv run --locked --script doc/examples/run_all.py
+      run: uv run --locked --with pillow --script doc/examples/run_all.py
     - name: Test documentation
       run: uv run --locked -m sphinx doc/ _build/ -b doctest

CONTRIBUTING.rst

@@ -9,23 +9,13 @@ Contributions are always welcome!
 Development Installation
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Instead of pip-installing the latest release from PyPI_, you should get the
+Instead of installing the latest release from PyPI_, you should get the
 newest development version from Github_::
 
    git clone https://github.com/sfstoolbox/sfs-python.git
    cd sfs-python
    uv sync
 
-This creates a virtual environment where the latest development version
-of the SFS Toolbox is installed.
-Note that you can activate this environment from any directory
-(e.g. one where you have some Python scripts using the ``sfs`` module),
-it doesn't have to be the directory where you cloned the Git repository.
-
-Wherever you activate that environment from,
-it will always stay up-to-date, even if you pull new
-changes from the Github repository or switch branches.
-
 .. _PyPI: https://pypi.org/project/sfs/
 .. _Github: https://github.com/sfstoolbox/sfs-python/
 
@@ -34,47 +24,40 @@ Building the Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you make changes to the documentation, you can re-create the HTML pages
-using Sphinx_.
-From the main ``sfs-python`` directory,
-you can install it and a few other necessary packages with::
-
-   uv pip install -r doc/requirements.txt
-
-To create the HTML pages, use::
+using Sphinx_.  From the main ``sfs-python`` directory, run::
 
-   uv run -m sphinx doc _build
+   uv run sphinx-build doc _build
 
 The generated files will be available in the directory ``_build/``.
 
-To create the PDF file, use::
+.. _Sphinx: http://sphinx-doc.org/
 
-   uv run -m sphinx doc _build -b latex
 
-Afterwards go to the folder ``_build/`` and run LaTeX to create the
-PDF file. If you don’t know how to create a PDF file from the LaTeX output, you
-should have a look at Latexmk_ (see also this `Latexmk tutorial`_).
+Running the Tests
+^^^^^^^^^^^^^^^^^
 
-It is also possible to automatically check if all links are still valid::
+You'll need pytest_, which will be installed automatically.
+To execute the tests, simply run::
 
-   uv run -m sphinx doc _build -b linkcheck
+   uv run pytest
 
-.. _Sphinx: http://sphinx-doc.org/
-.. _Latexmk: https://www.cantab.net/users/johncollins/latexmk/
-.. _Latexmk tutorial: https://mg.readthedocs.io/latexmk.html
+.. _pytest: https://pytest.org/
 
-Running the Tests
-^^^^^^^^^^^^^^^^^
 
-You'll need pytest_ for that.
-It can be installed with::
+Editable Installation
+^^^^^^^^^^^^^^^^^^^^^
 
-   uv pip install -r tests/requirements.txt
+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 ``sfs`` module, you can switch to a directory of your choice
+and enter this::
 
-To execute the tests, simply run::
+   uv init --bare
+   uv add --editable --no-workspace path/to/your/sfs/repo
 
-   uv run -m pytest
+You can install further packages with ``uv add`` and then run
+whatever you need with ``uv run``.
 
-.. _pytest: https://pytest.org/
 
 Creating a New Release
 ^^^^^^^^^^^^^^^^^^^^^^

doc/installation.rst

@@ -13,8 +13,14 @@ 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/.
 
+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 SFS package`_.
+
 .. _Python: https://www.python.org/
 .. _uv: https://docs.astral.sh/uv/
+.. _pip: https://packaging.python.org/en/latest/tutorials/installing-packages/
+.. _the SFS package: https://pypi.org/project/sfs/
 .. _NumPy: http://www.numpy.org/
 .. _SciPy: https://www.scipy.org/scipylib/
 .. _Matplotlib: https://matplotlib.org/
@@ -24,32 +30,74 @@ Installation
 
 First, create a new directory wherever you want, change into it, then run::
 
-    uv venv
-
-This will print instructions for how to `activate the environment`__.
-You should do that now!
+    uv init --bare
 
-__ https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment
+This will create a file named ``pyproject.toml`` for you.
+Use the ``--help`` flag to see other options.
 
-The Sound Field Synthesis Toolbox can be installed with::
+The Sound Field Synthesis Toolbox can now be installed with::
 
-    uv pip install sfs
+    uv add sfs
 
 This will automatically install the NumPy_ and SciPy_ libraries as well,
 which are needed by the SFS Toolbox.
+It will also create a file named ``uv.lock``, which tracks the exact versions
+of all installed packages.
 
 If you want to use the provided functions for plotting sound fields, you'll need
 Matplotlib_::
 
-    uv pip install matplotlib
+    uv add matplotlib
 
 However, since all results are provided as plain NumPy_ arrays, you should also
 be able to use any other plotting library of your choice to visualize the sound
 fields.
 
-The steps above need to be executed only once.
-Whenever you come back to this directory at a later time,
-you just need to activate the environment again.
+You might also want to install some other Python-related tools,
+e.g. JupyterLab_::
+
+    uv add jupyterlab
+
+.. _JupyterLab: https://jupyter.org/
+
+You get the gist: whatever you need, just ``uv add ...`` it!
+
+Once everything is installed, you can start working with the tool of your choice
+by simply prefixing it with ``uv run``, for example::
+
+    uv run jupyter lab
+
+Similarly, you can launch any other tool, like a text editor, an IDE etc.
+
+You can also simply create a Python file, let's say ``my_script.py``:
+
+.. code:: python
+
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import sfs
+
+    npw = sfs.util.direction_vector(np.radians(-45))
+    f = 300  # Hz
+    omega = 2 * np.pi * f
+
+    grid = sfs.util.xyz_grid([-2, 2], [-2, 2], 0, spacing=0.02)
+    array = sfs.array.circular(N=32, R=1.5)
+
+    d, selection, secondary_source = sfs.fd.wfs.plane_25d(
+        omega, array.x, array.n, npw)
+
+    p = sfs.fd.synthesize(d, selection, array, secondary_source, grid=grid)
+    sfs.plot2d.amplitude(p, grid)
+    sfs.plot2d.loudspeakers(array.x, array.n, selection * array.a, size=0.15)
+
+    plt.show()
+
+You can then run this script (assuming you installed ``matplotlib`` before) with::
+
+    uv run my_script.py
+
+In a similar way, you can run the :doc:`example-python-scripts`.
 
 If you want to install the latest development version of the SFS Toolbox, have a
 look at :doc:`contributing`.

doc/requirements.txt

@@ -22,6 +22,20 @@ Documentation = "https://sfs-python.readthedocs.io/"
 Repository = "https://github.com/sfstoolbox/sfs-python"
 Issues = "https://github.com/sfstoolbox/sfs-python/issues"
 
+[dependency-groups]
+dev = [{ include-group = "test" }, { include-group = "doc" }]
+test = [
+    "pytest",
+]
+doc = [
+    "sphinx>=8",
+    "sphinx-rtd-theme",
+    "nbsphinx",
+    "ipykernel",
+    "sphinxcontrib-bibtex>=2.1.4",
+    "matplotlib>=3",
+]
+
 [tool.setuptools.packages.find]
 include = ["sfs*"]
 

pyproject.toml

@@ -4,12 +4,15 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3"
-
-python:
-  install:
-    - method: pip
-      path: .
-    - requirements: doc/requirements.txt
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen
 
 sphinx:
   configuration: doc/conf.py