UCSBarchlab · fdxmw · Jun 23, 2026 · Jun 24, 2026 · Jun 24, 2026 · Jun 24, 2026
diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml
@@ -0,0 +1,36 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    paths:
+      - www/**
+      - docs/images/**
+      - docs/screenshots/**
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+    - uses: astral-sh/setup-uv@v6
+    - name: Generate pages with Sphinx
+      run: uv run just www
+    - name: Upload static files as artifact
+      id: deployment
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: www/_build/html
+
+  deploy:
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/python-release.yml b/.github/workflows/python-release.yml
@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
     - uses: astral-sh/setup-uv@v6
       with:
         enable-cache: true

diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml
@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
     - uses: astral-sh/setup-uv@v6
       with:
         enable-cache: true

diff --git a/README.md b/README.md
@@ -13,25 +13,25 @@ PyRTL
 PyRTL provides a collection of classes for Pythonic [register-transfer
 level](https://en.wikipedia.org/wiki/Register-transfer_level) design,
 simulation, tracing, and testing suitable for teaching and research.
-Simplicity, usability, clarity, and extensibility rather than performance or
-optimization is the overarching goal. Features include:
+Simplicity, usability, clarity, and extensibility are overarching goals, rather
+than performance or optimization. Features include:
 
 * Elaboration-through-execution, meaning all of Python can be used including
-  introspection
-* Design, instantiate, and simulate all in one file and without leaving Python
+  introspection.
+* Design, instantiate, and simulate all in one file and without leaving Python.
 * Export to, or import from, common HDLs (BLIF-in, Verilog-out currently
-  supported)
-* Examine execution with waveforms on the terminal or export to `.vcd` as
-  projects scale
-* Elaboration, synthesis, and basic optimizations all included
+  supported).
+* Examine execution with waveforms on the terminal or export to
+  [`.vcd`](https://en.wikipedia.org/wiki/Value_change_dump) as projects scale.
+* Elaboration, synthesis, and basic optimizations all included.
 * Small and well-defined internal core structure means writing new transforms
-  is easier
-* Batteries included means many useful components are already available and
-  more are coming every week
+  is easier.
+* Batteries included means many useful components are already available.
 
 What README would be complete without a screenshot? Below you can see the
-waveform rendered right on the terminal for a small state machine written in
-PyRTL.
+waveform rendered right on the terminal for a [small state
+machine](https://github.com/UCSBarchlab/PyRTL/blob/development/examples/example3-statemachine.py)
+written in PyRTL.
 
 ![Command-line waveform for PyRTL state machine](https://github.com/UCSBarchlab/PyRTL/blob/development/docs/screenshots/pyrtl-statemachine.png?raw=true "PyRTL State Machine Screenshot")
 
@@ -43,44 +43,46 @@ PyRTL.
   [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples)
   directory. You can also [try the examples on
   MyBinder](https://mybinder.org/v2/gh/UCSBarchlab/PyRTL/development?filepath=%2Fipynb-examples%2F).
-* Full reference documentation is available at https://pyrtl.readthedocs.io/
+* [Full reference documentation](https://pyrtl.readthedocs.io/) is available.
 
 ### Package Contents
 
-If you are just getting started with PyRTL it is suggested that you start with
-the
-[`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples)
-first to get a sense of the "thinking with PyRTLs" required to design hardware
-in this way. If you are looking for a deeper understanding, dive into the code
-for the object `Block`. It is the core data structure at the heart of PyRTL and
-defines its semantics at a high level -- everything is converted to or from the
-small, simple set of primitives defined there.
+If you are just getting started with PyRTL, try starting with the
+[`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples) to
+get a sense of the "thinking with PyRTLs" required to design hardware in this
+way. If you are looking for a deeper understanding, dive into the code for the
+object [`Block`](https://pyrtl.readthedocs.io/en/latest/blocks.html#blocks). It
+is the core data structure at the heart of PyRTL and defines its semantics at a
+high level -- everything is converted to or from the small, simple set of
+primitives defined there.
 
 The package contains the following files and directories:
 * [`pyrtl`](https://github.com/UCSBarchlab/PyRTL/tree/development/pyrtl)
-  The src directory for the module.
+  The module's source code.
 * [`pyrtl/rtllib/`](https://github.com/UCSBarchlab/PyRTL/tree/development/pyrtl/rtllib)
   Finished PyRTL libraries which are hopefully both useful and documented.
 * [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples)
-  A set of hardware design examples that show the main idea behind PyRTL.
+  A set of hardware design examples that show the main ideas behind PyRTL.
 * [`tests`](https://github.com/UCSBarchlab/PyRTL/tree/development/tests)
   A set of unit tests for PyRTL which you can run with `pytest`.
 * [`docs`](https://github.com/UCSBarchlab/PyRTL/tree/development/docs)
-  Location of the Sphinx documentation.
+  Documentation written in
+  [Sphinx](https://www.sphinx-doc.org/en/master/index.html)
+  [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer).
 
-### The PyRTL Development Environment
+### PyRTL Development Environment
 
-All PyRTL developers should use the exact same tools to avoid confusing
+All PyRTL developers should use the same tool versions 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`.
+PyRTL uses [`uv`](https://docs.astral.sh/uv/) to ensure all developers work in
+the same environment. `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/)
+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:
@@ -108,77 +110,78 @@ needed. `uv` caches installed software so future `uv` invocations will be fast.
   example, pick a `PyrtlError` that is not covered and add a unit test in
   [`tests`](https://github.com/UCSBarchlab/PyRTL/tree/development/tests)
   that will hit it.
-* After you have that down check in the [PyRTL
-  Issues](https://github.com/UCSBarchlab/PyRTL/issues) list for a feature that
-  is marked as "beginner friendly".
+* After you have that down check [PyRTL
+  Issues](https://github.com/UCSBarchlab/PyRTL/issues) for a feature that is
+  marked as "beginner friendly".
 * Once you have that down, ask for access to the PyRTL-research repo where we
-  keep a list of more advanced features and designs that could use more help!
+  keep experimental features and designs that could use more help!
 
 *Coding style*
 
 * All major functionality should have unit tests covering and documenting their
-  use
-* All public functions and methods should have useful docstrings
+  use.
+* All public functions and methods should have useful docstrings.
 * All code needs to conform to
-  [PEP8](https://www.python.org/dev/peps/pep-0008/) conventions
+  [PEP8](https://www.python.org/dev/peps/pep-0008/) conventions.
 * No new root-level dependencies on external libs, import locally if required
-  for special functions
+  for special functions.
 
 *Workflow*
 
-* A useful reference for working with Git is this [Git
-  tutorial](https://www.atlassian.com/git/tutorials/)
-* A useful Git Fork workflow for working on this repo is [found
-  here](http://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/)
+* [This Git tutorial](https://www.atlassian.com/git/tutorials/) is a useful
+  reference for working with Git.
+* [This blog
+  post](http://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/)
+  covers a useful Git Fork workflow for working on PyRTL.
 * The `development` branch is the primary stable working branch (everyone is
-  invited to submit pull requests)
-* Bugs and minor enhancements tracked directly through the [issue
-  tracker](https://github.com/UCSBarchlab/PyRTL/issues)
-* When posting a bug please post a small chunk of code that captures the bug,
-  e.g. [Issue #56](https://github.com/UCSBarchlab/PyRTL/issues/56)
-* When pushing a fix to a bug or enhancement please reference issue number in
+  invited to submit pull requests).,
+* Bugs and minor enhancements tracked directly through [GitHub
+  Issues](https://github.com/UCSBarchlab/PyRTL/issues).
+* When posting a bug please include a small code sample that triggers the bug,
+  e.g. [Issue #56](https://github.com/UCSBarchlab/PyRTL/issues/56).
+* When pushing a fix to a bug or enhancement please reference the Issue in the
   commit message, e.g. [Fix to Issue
-  #56](https://github.com/UCSBarchlab/PyRTL/commit/1d5730db168a9e4490c580cb930075715468047a)
+  #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.
+   to verify that all tests pass and that all documentation can be generated
+   with your changes.
 
 *Documentation*
 
 * All important functionality should have an executable example in
-  [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples)
-* All classes should have a block comment with high level description of the
-  class
-* All functions should follow the following (Sphinx parsable) docstring format:
+  [`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples).
+
+* All classes should have a [docstring](https://peps.python.org/pep-0257) that
+  describes the class at a high level.
+
+* All methods and functions should include a docstring in the following
+  Sphinx-parsable format:
   ```python
-  """One Line Summary (< 80 chars) of the function, followed by period.
+  """One Line Summary (< 88 chars) of the function, followed by period.
 
-  A long description of what this function does. Talk about what the user
-  should expect from this function and also what the users needs to do to use
-  the function (this part is optional).
+  A longer description of what this function does and does not do. Describe any
+  assumptions or invariants. Provide an example for user-facing functions.
 
-  :param param_name : Description of this parameter.
-  :param param_name : Longer parameter descriptions take up a newline with four
+  :param param1: Description of this parameter.
+  :param param2: Longer parameter descriptions take up a newline with four
       leading spaces like this.
+
+  :raises Exception: If this function raises an exception, explain when that
+      occurs here.
+
   :return: Description of function's return value.
   """
-  # Developer Notes (Optional):
-  #
-  # These would be anything that the user does not need to know in order to use
-  # the functions.
-  # These notes can include internal workings of the function, the logic behind
-  # it, or how to extend it.
   ```
 * Sphinx parses [Python type
   annotations](https://docs.python.org/3/library/typing.html), so put type
   information into annotations instead of docstrings.
 * The Sphinx-generated documentation is published to
-  https://pyrtl.readthedocs.io/
+  https://pyrtl.readthedocs.io/ .
 * PyRTL's Sphinx build process is documented in
   [`docs/README.md`](https://github.com/UCSBarchlab/PyRTL/blob/development/docs/README.md).
 * PyRTL's release process is documented in

diff --git a/docs/README.md b/docs/README.md
@@ -24,11 +24,9 @@ Follow the instructions on this page to build a local copy of PyRTL's
 documentation. This is useful for verifying that PyRTL's documentation still
 renders correctly after making a local change.
 
-There is additional PyRTL documentation in the [`gh-pages`
-branch](https://github.com/UCSBarchlab/PyRTL/tree/gh-pages). This additional
-documentation is pushed to https://ucsbarchlab.github.io/PyRTL/ by the
-`pages-build-deployment` GitHub Action. This additional documentation is
-written HTML and is not described further in this README.
+There is additional PyRTL documentation in [GitHub
+Pages](https://ucsbarchlab.github.io/PyRTL/), see
+[`www/README.md`](https://github.com/UCSBarchlab/PyRTL/blob/development/www/README.md).
 
 ## Testing Documentation Examples
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -23,8 +23,6 @@
 # -- Project information -----------------------------------------------------
 
 project = "PyRTL"
-copyright = "2026, Timothy Sherwood"
-author = "Timothy Sherwood"
 
 # -- General configuration ---------------------------------------------------
 
@@ -96,6 +94,9 @@
     ],
 }
 html_logo = "brand/pyrtl_logo.png"
+html_show_sphinx = False
+html_show_copyright = False
+html_show_sourcelink = False
 
 # Force a light blue background color for inheritance-diagrams. The default is
 # transparent, which does not work well with Furo's dark mode.

diff --git a/docs/images/gcd-graph.png b/docs/images/gcd-graph.png
diff --git a/docs/screenshots/adder.png b/docs/screenshots/adder.png
diff --git a/docs/screenshots/fir.png b/docs/screenshots/fir.png
diff --git a/docs/screenshots/gcd.png b/docs/screenshots/gcd.png
diff --git a/docs/screenshots/index-demo.png b/docs/screenshots/index-demo.png
diff --git a/docs/screenshots/maxn.png b/docs/screenshots/maxn.png
diff --git a/docs/screenshots/mul.png b/docs/screenshots/mul.png
diff --git a/docs/screenshots/pyrtl-counter.png b/docs/screenshots/pyrtl-counter.png
diff --git a/docs/screenshots/pyrtl-statemachine.png b/docs/screenshots/pyrtl-statemachine.png
diff --git a/docs/screenshots/render_trace.png b/docs/screenshots/render_trace.png
diff --git a/justfile b/justfile
@@ -1,7 +1,7 @@
 # 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.
-presubmit: tests docs
+presubmit: tests docs www
 
 tests:
         # Run `pytest` with the latest version of Python supported by PyRTL,
@@ -36,3 +36,9 @@ docs:
         #
         # Output: docs/_build/html/index.html
         uv run sphinx-build -M html docs/ docs/_build
+
+www:
+        # Run `sphinx-build` to generate github.io webpage.
+        #
+        # Output: www/_build/html/index.html
+        uv run sphinx-build -M html www/ www/_build
diff --git a/pyproject.toml b/pyproject.toml
@@ -127,4 +127,5 @@ dev = [
     "sphinx>=7.4.7",
     "sphinx-autodoc-typehints>=2.3.0",
     "sphinx-copybutton>=0.5.2",
+    "sphinx-design>=0.6.1",
 ]
diff --git a/tests/test_examples.py b/tests/test_examples.py
@@ -1,25 +1,27 @@
 import glob
+import itertools
 import os
 import subprocess
 
 import pytest
 
 import pyrtl
 
-"""
-Tests all of the files in the example folder
-
-Note that this file is structure dependent, so don't forget to change it if the relative
-location of the examples changes
-"""
-
 
 @pytest.mark.parametrize(
-    "file", glob.iglob(os.path.dirname(__file__) + "/../examples/*.py")
+    "file",
+    itertools.chain(
+        glob.iglob(os.path.dirname(__file__) + "/../examples/*.py"),
+        glob.iglob(os.path.dirname(__file__) + "/../www/*.py"),
+    ),
 )
 def test_all_examples(file):
+    """Test all scripts in ``examples/`` and ``www/``.
+
+    This just checks that all scripts terminate with exit status 0.
+    """
     pyrtl.reset_working_block()
     try:
         subprocess.check_output(["python", file])
-    except subprocess.CalledProcessError as e:
-        raise e
+    except subprocess.CalledProcessError:
+        pytest.fail(f"Failed to execute {file}")