Refactor README installation to recommend uv

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Documentation
 
+- Refactor `README.md` installation section to recommend uv as the
+  primary method for managing tinytopics as a project dependency,
+  with a canonical example for configuring PyTorch with GPU support (#80).
 - Remove reference to Rye in `README.md` installation instructions
   as it is no longer being developed (#79).
 

README.md

@@ -29,39 +29,39 @@ cd tinytopics
 python3 -m pip install -e .
 ```
 
-### Install PyTorch with GPU support
+### Using uv (recommended)
 
-The above will likely install the CPU version of PyTorch by default.
-To install PyTorch with GPU support, follow the
-[official guide](https://pytorch.org/get-started/locally/).
+For a more robust package management experience, use
+[uv](https://docs.astral.sh/uv/) to manage tinytopics as a project dependency.
 
-For example, install PyTorch for Windows with CUDA 13.0:
+Add tinytopics and PyTorch to your project:
 
 ```bash
-pip uninstall torch
-pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130
+uv add tinytopics torch torchvision
 ```
 
-### Install alternative PyTorch versions
+To install PyTorch with GPU support (for example, Windows with CUDA 13.0),
+configure `pyproject.toml`:
 
-For users stuck with older PyTorch or NumPy versions, for instance, in HPC
-cluster settings, a workaround is to skip installing the dependencies with
-`--no-deps` and install specific versions of all dependencies manually:
+```toml
+[tool.uv.sources]
+torch = [{ index = "pytorch-cu130", marker = "sys_platform == 'win32'" }]
+torchvision = [{ index = "pytorch-cu130", marker = "sys_platform == 'win32'" }]
 
-```bash
-pip install tinytopics --no-deps
-pip install torch==2.2.0
+[[tool.uv.index]]
+name = "pytorch-cu130"
+url = "https://download.pytorch.org/whl/cu130"
+explicit = true
 ```
 
-### Use tinytopics in a project
+Then sync your environment:
 
-To have a more hassle-free package management experience, it is recommended
-to use tinytopics as a dependency under a project context using
-virtual environments.
+```bash
+uv sync
+```
 
-You should probably set up a manual source/index for PyTorch.
-As an example, check out the official guidelines when
-[using uv](https://docs.astral.sh/uv/guides/integration/pytorch/).
+For other platforms and accelerators (CPU-only, ROCm, Intel GPUs), see
+[Using uv with PyTorch](https://docs.astral.sh/uv/guides/integration/pytorch/).
 
 ## Examples
 

docs/changelog.md

@@ -4,6 +4,9 @@
 
 ### Documentation
 
+- Refactor `README.md` installation section to recommend uv as the
+  primary method for managing tinytopics as a project dependency,
+  with a canonical example for configuring PyTorch with GPU support (#80).
 - Remove reference to Rye in `README.md` installation instructions
   as it is no longer being developed (#79).
 

docs/index.md

@@ -29,39 +29,39 @@ cd tinytopics
 python3 -m pip install -e .
 ```
 
-### Install PyTorch with GPU support
+### Using uv (recommended)
 
-The above will likely install the CPU version of PyTorch by default.
-To install PyTorch with GPU support, follow the
-[official guide](https://pytorch.org/get-started/locally/).
+For a more robust package management experience, use
+[uv](https://docs.astral.sh/uv/) to manage tinytopics as a project dependency.
 
-For example, install PyTorch for Windows with CUDA 13.0:
+Add tinytopics and PyTorch to your project:
 
 ```bash
-pip uninstall torch
-pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130
+uv add tinytopics torch torchvision
 ```
 
-### Install alternative PyTorch versions
+To install PyTorch with GPU support (for example, Windows with CUDA 13.0),
+configure `pyproject.toml`:
 
-For users stuck with older PyTorch or NumPy versions, for instance, in HPC
-cluster settings, a workaround is to skip installing the dependencies with
-`--no-deps` and install specific versions of all dependencies manually:
+```toml
+[tool.uv.sources]
+torch = [{ index = "pytorch-cu130", marker = "sys_platform == 'win32'" }]
+torchvision = [{ index = "pytorch-cu130", marker = "sys_platform == 'win32'" }]
 
-```bash
-pip install tinytopics --no-deps
-pip install torch==2.2.0
+[[tool.uv.index]]
+name = "pytorch-cu130"
+url = "https://download.pytorch.org/whl/cu130"
+explicit = true
 ```
 
-### Use tinytopics in a project
+Then sync your environment:
 
-To have a more hassle-free package management experience, it is recommended
-to use tinytopics as a dependency under a project context using
-virtual environments.
+```bash
+uv sync
+```
 
-You should probably set up a manual source/index for PyTorch.
-As an example, check out the official guidelines when
-[using uv](https://docs.astral.sh/uv/guides/integration/pytorch/).
+For other platforms and accelerators (CPU-only, ROCm, Intel GPUs), see
+[Using uv with PyTorch](https://docs.astral.sh/uv/guides/integration/pytorch/).
 
 ## Examples