From 455df0adff8644cec687980f53f4782c041783e6 Mon Sep 17 00:00:00 2001 From: Jeremy Lau <30300826+fdxmw@users.noreply.github.com> Date: Tue, 6 Oct 2026 15:07:56 -0700 Subject: [PATCH] Move webpage examples to the main `examples` directory. This also moves the webpage notebooks to the main `ipynb-examples` directory. This puts all of PyRTL's examples in one place, so they are easier to find, and simplifies the repository's directory structure. --- examples/README.md | 21 +++++----------- {www/examples => examples}/example-adder.py | 0 {www/examples => examples}/example-fir.py | 2 +- {www/examples => examples}/example-gcd.py | 0 {www/examples => examples}/example-maxn.py | 0 {www/examples => examples}/example-mul.py | 0 .../example-ripple-carry.py | 0 .../example-adder.ipynb | 0 .../example-fir.ipynb | 2 +- .../example-gcd.ipynb | 0 .../example-maxn.ipynb | 0 .../example-mul.ipynb | 0 .../example-ripple-carry.ipynb | 0 pyproject.toml | 2 +- tests/test_examples.py | 10 +++----- www/conf.py | 2 +- www/examples/Makefile | 10 -------- www/examples/README.md | 6 ----- www/index.rst | 24 +++++++++---------- 19 files changed, 25 insertions(+), 54 deletions(-) rename {www/examples => examples}/example-adder.py (100%) rename {www/examples => examples}/example-fir.py (93%) rename {www/examples => examples}/example-gcd.py (100%) rename {www/examples => examples}/example-maxn.py (100%) rename {www/examples => examples}/example-mul.py (100%) rename {www/examples => examples}/example-ripple-carry.py (100%) rename {www/ipynb-examples => ipynb-examples}/example-adder.ipynb (100%) rename {www/ipynb-examples => ipynb-examples}/example-fir.ipynb (97%) rename {www/ipynb-examples => ipynb-examples}/example-gcd.ipynb (100%) rename {www/ipynb-examples => ipynb-examples}/example-maxn.ipynb (100%) rename {www/ipynb-examples => ipynb-examples}/example-mul.ipynb (100%) rename {www/ipynb-examples => ipynb-examples}/example-ripple-carry.ipynb (100%) delete mode 100644 www/examples/Makefile delete mode 100644 www/examples/README.md diff --git a/examples/README.md b/examples/README.md index 29561675..d698f3bf 100644 --- a/examples/README.md +++ b/examples/README.md @@ -14,27 +14,18 @@ or interactively with: uv run python3 -i $SCRIPT_FILE ``` -PyRTL has examples in two directories: -[`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples) -and -[`www/examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/www/examples). - ## Generating Jupyter Notebooks -Each example script is automatically converted to a Jupyter notebook in a -corresponding `ipynb-examples` directory, +Each example script is automatically converted to a Jupyter notebook in the [`ipynb-examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/ipynb-examples) -and -[`www/ipynb-examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/www/ipynb-examples). +directory. [`examples/tools/to_ipynb.py`](https://github.com/UCSBarchlab/PyRTL/blob/development/examples/tools/to_ipynb.py) -does these automatic conversions. Do not manually edit the generated Jupyter +performs these conversions. Do not manually edit the generated Jupyter notebooks! Any manual changes will be lost the next time someone runs `to_ipynb.py`. If you update an example script, re-run `to_ipynb.py` to update its corresponding Jupyter notebook. This process is automated with -[`examples/Makefile`](https://github.com/UCSBarchlab/PyRTL/blob/development/examples/Makefile) -and -[`www/examples/Makefile`](https://github.com/UCSBarchlab/PyRTL/blob/development/www/examples/Makefile). -Running `make` in these directories will re-generate Jupyter notebooks for any -modified examples in their `examples` directory. +[`examples/Makefile`](https://github.com/UCSBarchlab/PyRTL/blob/development/examples/Makefile). +Running `make` in the `examples` directory will re-generate Jupyter notebooks +for any modified examples. diff --git a/www/examples/example-adder.py b/examples/example-adder.py similarity index 100% rename from www/examples/example-adder.py rename to examples/example-adder.py diff --git a/www/examples/example-fir.py b/examples/example-fir.py similarity index 93% rename from www/examples/example-fir.py rename to examples/example-fir.py index bf708882..0a1beeda 100644 --- a/www/examples/example-fir.py +++ b/examples/example-fir.py @@ -1,6 +1,6 @@ import pyrtl -# # Finite impulse filter example. +# # Finite impulse response filter example. def fir(x: pyrtl.WireVector, bs: list[int]): diff --git a/www/examples/example-gcd.py b/examples/example-gcd.py similarity index 100% rename from www/examples/example-gcd.py rename to examples/example-gcd.py diff --git a/www/examples/example-maxn.py b/examples/example-maxn.py similarity index 100% rename from www/examples/example-maxn.py rename to examples/example-maxn.py diff --git a/www/examples/example-mul.py b/examples/example-mul.py similarity index 100% rename from www/examples/example-mul.py rename to examples/example-mul.py diff --git a/www/examples/example-ripple-carry.py b/examples/example-ripple-carry.py similarity index 100% rename from www/examples/example-ripple-carry.py rename to examples/example-ripple-carry.py diff --git a/www/ipynb-examples/example-adder.ipynb b/ipynb-examples/example-adder.ipynb similarity index 100% rename from www/ipynb-examples/example-adder.ipynb rename to ipynb-examples/example-adder.ipynb diff --git a/www/ipynb-examples/example-fir.ipynb b/ipynb-examples/example-fir.ipynb similarity index 97% rename from www/ipynb-examples/example-fir.ipynb rename to ipynb-examples/example-fir.ipynb index c17c6ae3..439aaeb4 100644 --- a/www/ipynb-examples/example-fir.ipynb +++ b/ipynb-examples/example-fir.ipynb @@ -19,7 +19,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - " # Finite impulse filter example.\n" + " # Finite impulse response filter example.\n" ] }, { diff --git a/www/ipynb-examples/example-gcd.ipynb b/ipynb-examples/example-gcd.ipynb similarity index 100% rename from www/ipynb-examples/example-gcd.ipynb rename to ipynb-examples/example-gcd.ipynb diff --git a/www/ipynb-examples/example-maxn.ipynb b/ipynb-examples/example-maxn.ipynb similarity index 100% rename from www/ipynb-examples/example-maxn.ipynb rename to ipynb-examples/example-maxn.ipynb diff --git a/www/ipynb-examples/example-mul.ipynb b/ipynb-examples/example-mul.ipynb similarity index 100% rename from www/ipynb-examples/example-mul.ipynb rename to ipynb-examples/example-mul.ipynb diff --git a/www/ipynb-examples/example-ripple-carry.ipynb b/ipynb-examples/example-ripple-carry.ipynb similarity index 100% rename from www/ipynb-examples/example-ripple-carry.ipynb rename to ipynb-examples/example-ripple-carry.ipynb diff --git a/pyproject.toml b/pyproject.toml index 8eb5b98e..d446bfd2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,7 +55,7 @@ Changelog = "https://github.com/UCSBarchlab/PyRTL/blob/development/CHANGELOG.md" source = "vcs" [tool.ruff] -exclude = ["ipynb-examples", "docs/_build", "www/_build", "www/ipynb-examples"] +exclude = ["ipynb-examples", "docs/_build", "www/_build"] [tool.ruff.lint] # See https://docs.astral.sh/ruff/rules/ diff --git a/tests/test_examples.py b/tests/test_examples.py index d2d7736a..f87b56ac 100644 --- a/tests/test_examples.py +++ b/tests/test_examples.py @@ -7,16 +7,12 @@ def get_scripts(directory: str) -> list[Path]: - return list((Path(os.path.dirname(__file__)) / ".." / directory).glob("*.py")) + return list((Path(os.path.dirname(__file__)) / directory).glob("*.py")) -@pytest.mark.parametrize( - "file", - get_scripts("examples") + get_scripts("www/examples"), - ids=lambda path: path.name, -) +@pytest.mark.parametrize("file", get_scripts("../examples"), ids=lambda path: path.name) def test_all_examples(file): - """Test all Python scripts in ``examples/`` and ``www/examples``. + """Test all Python scripts in ``examples/``. This just checks that all Python scripts terminate with exit status 0. """ diff --git a/www/conf.py b/www/conf.py index a43fb3db..5e5ee022 100644 --- a/www/conf.py +++ b/www/conf.py @@ -28,7 +28,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["examples", "ipynb-examples", "_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # Enable links to Python standard library classes (str, list, dict, etc). intersphinx_mapping = { diff --git a/www/examples/Makefile b/www/examples/Makefile deleted file mode 100644 index 2ae421ce..00000000 --- a/www/examples/Makefile +++ /dev/null @@ -1,10 +0,0 @@ -PYTHON := uv run -TO_IPYNB := ../../examples/tools/to_ipynb.py -PY_FILES := $(wildcard example*.py) -IPYNB_FILES := $(addprefix ../ipynb-examples/, $(PY_FILES:.py=.ipynb)) - -all: $(IPYNB_FILES) - -# Convert a PyRTL example Python script to a Jupyter notebook. -../ipynb-examples/%.ipynb: %.py $(TO_IPYNB) - $(PYTHON) $(TO_IPYNB) $< $@ diff --git a/www/examples/README.md b/www/examples/README.md deleted file mode 100644 index 393b8019..00000000 --- a/www/examples/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# PyRTL's Webpage Examples - -See the main -[`examples`](https://github.com/UCSBarchlab/PyRTL/tree/development/examples) -documentation in -[`examples/README.md`](https://github.com/UCSBarchlab/PyRTL/blob/development/examples/README.md). diff --git a/www/index.rst b/www/index.rst index d766b9f3..d32a5072 100644 --- a/www/index.rst +++ b/www/index.rst @@ -115,11 +115,11 @@ differences between the approaches. The code below provides everything needed to instantiate, simulate, and visualize the resulting design. - .. jupyterlite:: ipynb-examples/example-gcd.ipynb + .. jupyterlite:: ../ipynb-examples/example-gcd.ipynb :new_tab: True :new_tab_button_text: Try this example in your browser - .. literalinclude:: examples/example-gcd.py + .. literalinclude:: ../examples/example-gcd.py .. image:: ../docs/screenshots/gcd.png :width: 16em @@ -134,11 +134,11 @@ differences between the approaches. an output ``y`` which is the resulting sum of products and is valid every cycle (since the design is naturally fully pipelined). - .. jupyterlite:: ipynb-examples/example-fir.ipynb + .. jupyterlite:: ../ipynb-examples/example-fir.ipynb :new_tab: True :new_tab_button_text: Try this example in your browser - .. literalinclude:: examples/example-fir.py + .. literalinclude:: ../examples/example-fir.py .. image:: ../docs/screenshots/fir.png :width: 30em @@ -154,11 +154,11 @@ differences between the approaches. like :func:`~functools.reduce`, which is used to chain together multiple ``max_2`` elements into a bigger ``max_n``. - .. jupyterlite:: ipynb-examples/example-maxn.ipynb + .. jupyterlite:: ../ipynb-examples/example-maxn.ipynb :new_tab: True :new_tab_button_text: Try this example in your browser - .. literalinclude:: examples/example-maxn.py + .. literalinclude:: ../examples/example-maxn.py .. image:: ../docs/screenshots/maxn.png :width: 15em @@ -176,11 +176,11 @@ differences between the approaches. an 8-bit ROM address and returns the value stored in the ROM at that address. - .. jupyterlite:: ipynb-examples/example-mul.ipynb + .. jupyterlite:: ../ipynb-examples/example-mul.ipynb :new_tab: True :new_tab_button_text: Try this example in your browser - .. literalinclude:: examples/example-mul.py + .. literalinclude:: ../examples/example-mul.py .. image:: ../docs/screenshots/mul.png :width: 15em @@ -197,11 +197,11 @@ differences between the approaches. final ``full_sum`` is produced by concatenating the wires in ``sum`` with :func:`~pyrtl.concat_list`. - .. jupyterlite:: ipynb-examples/example-adder.ipynb + .. jupyterlite:: ../ipynb-examples/example-adder.ipynb :new_tab: True :new_tab_button_text: Try this example in your browser - .. literalinclude:: examples/example-adder.py + .. literalinclude:: ../examples/example-adder.py .. image:: ../docs/screenshots/adder.png :width: 15em @@ -255,11 +255,11 @@ introduction to fixed 4-bit adders `_, let's go ahead and build an `arbitrary` bitwidth adder. -.. jupyterlite:: ipynb-examples/example-ripple-carry.ipynb +.. jupyterlite:: ../ipynb-examples/example-ripple-carry.ipynb :new_tab: True :new_tab_button_text: Try this example in your browser -.. literalinclude:: examples/example-ripple-carry.py +.. literalinclude:: ../examples/example-ripple-carry.py The code above includes ``ripple_add``, an adder generator with Python-style slices on wires, ``counter``, an instance of :class:`~pyrtl.Register`, and all