Migrate PyRTL to uv. This has several advantages:

* The new workflow is about twice as fast as the old one on my computer.
* `uv` manages installation of the appropriate versions of Python and all pip
  packages, greatly simplifying the  creation of PyRTL development
  environments
* This pins all developer tools to specific versions. Previously we only pinned
  documentation tools. This avoids confusing situations where lint errors
  suddenly appear just because a new version of `ruff` was released.

To run all tests with the new workflow:

```
$ uv run just tests
```

To build documentation with the new workflow:

```
$ uv run just docs
```

This replaces the old `tox` based workflow with a new `just` based workflow.
`tox` is no longer needed since `uv` manages all virtual environments. `just`
is used instead, as a simple portable task runner.

Author: fdxmw

.github/workflows/python-test.yml

@@ -5,24 +5,18 @@ on:
   - pull_request
 
 jobs:
-  test:
+  tests:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        # When changing the following line, be sure to update `envlist` in
-        # tox.ini
-        python-version: [3.9, 3.13]
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+    - uses: astral-sh/setup-uv@v6
       with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: python3 -m pip install tox tox-gh-actions
-    - name: Test with tox
-      run: tox
+        enable-cache: true
+    - name: Install apt dependencies
+      run: sudo apt install -y yosys
+    - name: Run tests
+      run: uv run just tests
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
       env:

.python-version

@@ -0,0 +1 @@
+3.13

.readthedocs.yaml

@@ -11,8 +11,15 @@ build:
   tools:
     # Use the latest 3.x version available on Read the Docs.
     python: "3"
-  apt_packages:
-    - graphviz
+  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
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -21,8 +28,3 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF
 formats:
    - pdf
-
-# Optionally set the requirements required to build your docs
-python:
-   install:
-     - requirements: docs/requirements.txt

README.md

@@ -68,20 +68,36 @@ The package contains the following files and directories:
 * [`docs`](https://github.com/UCSBarchlab/PyRTL/tree/development/docs)
   Location of the Sphinx documentation.
 
-Testing requires the Python packages `tox` and `pytest`, which are installed by
-`requirements.txt`. Once installed, a complete test of the system can be run with:
+### The PyRTL Development Environment
+
+All PyRTL developers should use the exact same tools to avoid confusing
+situations where a test fails only on one person's computer, or the generated
+documentation looks weird on another person's computer.
+
+PyRTL uses [`uv`](https://docs.astral.sh/uv/) to ensure everyone's development
+environments are consistent. `uv` manages the installation and versioning for
+all other PyRTL developer tools, like `pytest` and `ruff`.
+
+So to set up a PyRTL development environment, you only need to install `uv`, by
+following the
+[`uv` installation instructions](https://docs.astral.sh/uv/getting-started/installation/)
+
+After installing [`uv`](https://docs.astral.sh/uv/), you can run all the tests
+with:
 
 ```shell
-$ tox
+$ uv run just tests
 ```
 
-PyRTL's code is automatically formatted with `ruff`, also installed by
-`requirements.txt`. Reformat any changed code with:
+And you can generate the Sphinx documentation with:
 
 ```shell
-$ ruff format
+$ uv run just docs
 ```
 
+`uv` will download and install Python and any required `pip` packages as
+needed. `uv` caches installed software so future `uv` invocations will be fast.
+
 ### Contributing to PyRTL
 
 *Picking a first project*

docs/Makefile

@@ -52,52 +52,16 @@ not worth showing in every example. These blocks look like:
     >>> pyrtl.reset_working_block()
 ```
 
-## Installing Sphinx
-
-Sphinx and its dependencies are all pinned to specific versions for
-[reproducible documentation builds](https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html).
-This avoids problems where documentation builds randomly fail due to bugs or
-incompatibilities in the newest version of Sphinx or one of its
-dependencies.
-
-Use of an environment manager like [`conda`](https://docs.conda.io/en/latest/)
-or [`virtualenv`](https://virtualenv.pypa.io/en/latest/) is strongly
-recommended. To install Sphinx locally, run the following commands from the
-repository root:
-
-```shell
-# Install Sphinx.
-$ pip install --upgrade -r docs/requirements.txt
-```
-
-## Installing Graphviz
-
-[Install graphviz](https://www.graphviz.org/download/#executable-packages). Use
-of a package manager like
-[`apt`](https://ubuntu.com/server/docs/package-management) or
-[`brew`](https://brew.sh/) is strongly recommended. Instructions vary depending
-on your operating system, see the installation link for details.
-
 ## Running Sphinx
 
-Run Sphinx with the provided [`docs/Makefile`](https://github.com/UCSBarchlab/PyRTL/blob/development/docs/Makefile):
+Run Sphinx with the provided
+[`justfile`](https://github.com/UCSBarchlab/PyRTL/blob/development/justfile),
+from the repository's root directory:
 
 ```shell
 # Run Sphinx to build PyRTL's documentation.
-$ make -C docs
-```
-
-A local copy of PyRTL's documentation should be available in
-`docs/_build/html`. `docs/_build/html/index.html` is the home page.
-
-## Updating Sphinx
-
-To update the pinned version of Sphinx, run
-
-```shell
-# Run pip-compile to generate docs/requirements.txt from docs/requirements.in.
-$ make -C docs requirements.txt
+$ uv run just docs
 ```
 
-It's a good idea to update the pinned version of Sphinx whenever you update the
-documentation.
+This builds a local copy of PyRTL's documentation in `docs/_build/html`.
+`docs/_build/html/index.html` is the home page.

docs/README.md

@@ -0,0 +1,36 @@
+# PyRTL uses `just` instead of `make` because:
+# * `make` is not installed by default on Windows.
+# * `uv` can install `just` on all supported platforms from PyPI.
+tests:
+        # Run `pytest` with the latest version of Python supported by PyRTL,
+        # which is the default for `uv`. The default is set with `uv python
+        # pin` and written to `.python_version`.
+        uv run pytest -n auto --cov=pyrtl --cov-report=xml
+
+        # Run `pytest` in an isolated virtual environment, with the earliest
+        # version of Python supported by PyRTL.
+        uv run --python=3.9 --isolated pytest -n auto
+
+        # Run `ruff format` to check that code is formatted properly.
+        #
+        # If this fails, try running
+        #
+        # $ uv run ruff format
+        #
+        # to automatically reformat any changed code.
+        uv run ruff format --diff
+
+        # Run `ruff check` to check for lint errors.
+        #
+        # If this fails, try running
+        #
+        # $ uv run ruff check --fix
+        #
+        # to automatically apply fixes, when possible.
+        uv run ruff check
+
+docs:
+        # Run `sphinx-build` to generate documentation.
+        #
+        # Output: docs/_build/html/index.html
+        uv run sphinx-build -M html docs/ docs/_build

docs/requirements.in

@@ -37,6 +37,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
     "Topic :: System :: Hardware",
 ]
+dependencies = []
 
 [project.optional-dependencies]
 # Required by `input_from_blif`.
@@ -112,3 +113,18 @@ ignore = [
     # `__all__` is not sorted
     "RUF022",
 ]
+
+[dependency-groups]
+dev = [
+    "furo>=2025.9.25",
+    "graphviz>=0.21",
+    "pyparsing>=3.2.5",
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.14.2",
+    "rust-just>=1.43.0",
+    "sphinx>=7.4.7",
+    "sphinx-autodoc-typehints>=2.3.0",
+    "sphinx-copybutton>=0.5.2",
+]