Migrate PyRTL to uv (#476)

* Migrate PyRTL to `uv`. This has several advantages:

* The new workflow is significantly faster on my computer:
  ```
  $ # New workflow
  $ uv run just tests
  ...
  real    0m11.830s
  user    1m31.411s
  sys     0m7.255s
  ```

  ```
  $ # Old workflow
  $ tox
  ...
  real    0m19.537s
  user    2m2.577s
  sys     0m7.972s
  ```
* `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
```

To run both:
```
$ uv run just presubmit
```

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-release.yml

@@ -18,14 +18,11 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
+    - uses: astral-sh/setup-uv@v6
       with:
-        python-version: "3.x"
-    - name: Install pypa/build
-      run: python3 -m pip install build
+        enable-cache: true
     - name: Build distribution archives
-      run: python3 -m build
+      run: uv build
     - name: Upload distribution archives
       uses: actions/upload-artifact@v4
       with:

.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

@@ -13,6 +13,15 @@ build:
     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 +30,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*
@@ -123,6 +139,14 @@ $ ruff format
 * When pushing a fix to a bug or enhancement please reference issue number in
   commit message, e.g. [Fix to Issue
   #56](https://github.com/UCSBarchlab/PyRTL/commit/1d5730db168a9e4490c580cb930075715468047a)
+* Before sending a pull request, please run:
+
+   ```shell
+   $ uv run just presubmit
+   ```
+
+   to verify that all tests pass and that documentation can be generated with
+   your changes.
 
 *Documentation*
 

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

@@ -124,23 +124,21 @@ commands.
 
 ### Manual build
 
-1. Update build tools:
-   ```shell
-   $ pip install  --upgrade -r release/requirements.txt
-   ```
-2. Build distribution archive:
-   ```shell
-   $ python3 -m build
-   ```
-   This produces two files in `dist/`: a `.whl` file and a `.tar.gz` file.
+Build distribution archive:
+
+```shell
+$ uv build
+```
+
+This produces two files in `dist/`: a `.whl` file and a `.tar.gz` file.
 
 ### Manual publish on TestPyPI
 
 1. If necessary, create a TestPyPI API token, by going to
    https://test.pypi.org/manage/account/ and clicking 'Add API token'.
 2. Upload distribution archive to TestPyPI:
    ```shell
-   $ twine upload --repository testpypi dist/*
+   $ uv run --with twine twine upload --repository testpypi dist/*
    ```
 3. Enter your API token when prompted.
 4. Check the new release's status at https://test.pypi.org/project/pyrtl/#history
@@ -156,7 +154,7 @@ commands.
    https://pypi.org/manage/account/ and clicking 'Add API token'.
 2. Upload distribution archive to PyPI:
    ```shell
-   $ twine upload dist/*
+   $ uv run --with twine twine upload dist/*
    ```
 3. Enter your API token when prompted.
 4. Check the new release's status at https://pypi.org/project/pyrtl/#history