From 63dc9f5c5e2523d78f5af2aeee3a526083d423af Mon Sep 17 00:00:00 2001
From: Jeremy Lau <30300826+fdxmw@users.noreply.github.com>
Date: Thu, 11 Apr 2024 07:37:31 -0700
Subject: [PATCH] Upgrade GitHub actions to latest versions to fix deprecation
warnings
Also:
- Add more documentation links to README
- Clean up requirements.txt
---
.github/workflows/python-release.yml | 5 +-
.github/workflows/python-test.yml | 10 +-
README.md | 185 ++++++++++++++++++---------
docs/images/gcd-graph.png | Bin 0 -> 85012 bytes
requirements.txt | 3 +-
5 files changed, 132 insertions(+), 71 deletions(-)
create mode 100644 docs/images/gcd-graph.png
diff --git a/.github/workflows/python-release.yml b/.github/workflows/python-release.yml
index 230097f8..18d9b872 100644
--- a/.github/workflows/python-release.yml
+++ b/.github/workflows/python-release.yml
@@ -20,7 +20,7 @@ jobs:
steps:
- uses: actions/checkout@v4
- name: Set up Python
- uses: actions/setup-python@v4
+ uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Install pypa/build
@@ -28,10 +28,11 @@ jobs:
- name: Build distribution archives
run: python3 -m build
- name: Upload distribution archives
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v4
with:
name: python-distribution-archives
path: dist/
+ compression-level: 0
# Publish distribution archive to TestPyPI on tag pushes.
publish-to-testpypi:
diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml
index 5f436b95..7252fc9b 100644
--- a/.github/workflows/python-test.yml
+++ b/.github/workflows/python-test.yml
@@ -14,14 +14,14 @@ jobs:
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v4
+ uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
- run: |
- python -m pip install --upgrade pip
- pip install tox tox-gh-actions
+ run: python3 -m pip install tox tox-gh-actions
- name: Test with tox
run: tox
- name: Upload coverage to Codecov
- uses: codecov/codecov-action@v3
+ uses: codecov/codecov-action@v4
+ env:
+ CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
diff --git a/README.md b/README.md
index 8def9ca6..7cdd487c 100644
--- a/README.md
+++ b/README.md
@@ -2,95 +2,156 @@ PyRTL
=====
[![PyPI version](https://badge.fury.io/py/pyrtl.svg)](http://badge.fury.io/py/pyrtl)
-[![Build Status](https://github.com/UCSBarchlab/PyRTL/actions/workflows/python-package.yml/badge.svg)](https://github.com/UCSBarchlab/PyRTL/actions)
+[![Build Status](https://github.com/UCSBarchlab/PyRTL/actions/workflows/python-test.yml/badge.svg)](https://github.com/UCSBarchlab/PyRTL/actions/workflows/python-test.yml)
[![Code Coverage](https://codecov.io/github/UCSBarchlab/PyRTL/coverage.svg?branch=development)](https://codecov.io/github/UCSBarchlab/PyRTL?branch=development)
[![Documentation Status](https://readthedocs.org/projects/pyrtl/badge/?version=latest)](http://pyrtl.readthedocs.org/en/latest/?badge=latest)
[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/UCSBarchlab/PyRTL/development?filepath=%2Fipynb-examples%2F)
-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:
+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:
-* Elaboration-through-execution, meaning all of Python can be used including introspection
+* Elaboration-through-execution, meaning all of Python can be used including
+ 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 a .vcd as projects scale
+* 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
-* 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
+* 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
-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.
+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.
![Command-line waveform for PyRTL state machine]( docs/screenshots/pyrtl-statemachine.png?raw=true "PyRTL State Machine Screenshot")
-For users, more info and demo code is available on the [PyRTL project web page](http://ucsbarchlab.github.io/PyRTL/).
+### Tutorials and Documentation
-### Package Contents
-
-If you are just getting started with PyRTL it is suggested that you start with the 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.
+* For users, more info and demo code is available on the [PyRTL project web
+ page](http://ucsbarchlab.github.io/PyRTL/).
+* Try the examples in the `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/
-In the package you should find the following files and Directories
-* **pyrtl/** The src directory for the module
-* **pyrtl/rtllib/** Finished PyRTL libraries which are hopefully both useful and documented
-* **examples/** A set of hardware design examples that show the main idea behind pyrtl
-* **tests/** A set of unit tests for PyRTL which you can run with `pytest`
-* **docs/** Location of the sphinx documentation
+### Package Contents
-Testing requires the packages `tox` and `pytest`. Once installed a complete test of the system should be possible with the simple command `tox` and nothing more.
+If you are just getting started with PyRTL it is suggested that you start with
+the `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.
+
+The package contains the following files and directories:
+* **`pyrtl/`** The src directory for the module
+* **`pyrtl/rtllib/`** Finished PyRTL libraries which are hopefully both useful
+ and documented
+* **`examples/`** A set of hardware design examples that show the main idea
+ behind pyrtl
+* **`tests/`** A set of unit tests for PyRTL which you can run with `pytest`
+* **`docs/`** Location of the sphinx documentation
+
+Testing requires the Python packages `tox` and `pytest`. Once installed a
+complete test of the system should be possible with the simple command `tox`
+and nothing more.
### Contributing to PyRTL
*Picking a first project*
-* One of the earliest things you should submit is a unit test that hits some [uncovered lines of code in PyRTL](https://codecov.io/github/UCSBarchlab/PyRTL?branch=development). For example, pick a PyrtlError that is not covered and add a unit test in /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".
-* 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!
+* One of the earliest things you should submit is a unit test that hits some
+ [uncovered lines of code in
+ PyRTL](https://codecov.io/github/UCSBarchlab/PyRTL?branch=development). For
+ example, pick a `PyrtlError` that is not covered and add a unit test in
+ `/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".
+* 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!
*Coding style*
-* All major functionality should have set of unit tests covering and documenting their use
+* All major functionality should have unit tests covering and documenting their
+ 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
-* No new root-level dependencies on external libs, import locally if required for special functions
+* All code needs to conform to
+ [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
*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/)
-* The "master" branch should always be stable and is updated only on major revisions (with a merge from "development" by the core development team)
-* 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 commit message, e.g. [Fix to Issue #56](https://github.com/UCSBarchlab/PyRTL/commit/1d5730db168a9e4490c580cb930075715468047a)
+* 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/)
+* 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
+ commit message, e.g. [Fix to Issue
+ #56](https://github.com/UCSBarchlab/PyRTL/commit/1d5730db168a9e4490c580cb930075715468047a)
*Documentation*
-* All important functionality, for both /pyrtl and /rtlib, should have an executable example in /examples
-* All classes should have a block comment with high level description of the class
-* All functions in /pyrtl or /rtllib should follow the following (sphynx parsable) docstring format:
-```python
-""" One Line Summary (< 80 chars) on what the function does, followed by period.
-
-:param [optional param type] param_name : parameter description
-:param [optional param type] param_name : Longer parameter descriptions take up a newline
- with two leading spaces like this
-:return [optional return type]: return description
-
-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)
-"""
-
-# Developer Notes (Optional):
-# These would be anything that the user does not need to know in order to use the functions.
-# Such things include internal workings of the function, the logic behind it, how to extend
-# it (unless the function was mainly intended to be extended).
-```
-
-### Using PyRTL
-We love to hear from users about their projects, and if there are issues we will try our best to push fixes quickly. You can read more about how we have been using it in our research at UCSB both in simulation and on FPGAs in [our PyRTL paper at FPL](http://www.cs.ucsb.edu/~sherwood/pubs/FPL-17-pyrtl.pdf).
+
+* All important functionality should have an executable example in `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:
+ ```python
+ """One Line Summary (< 80 chars) of the function, followed by period.
+
+ :param param_name : Description of this parameter.
+ :param param_name : Longer parameter descriptions take up a newline with four
+ leading spaces like this.
+ :return: Description of function's return value.
+
+ 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).
+
+ """
+
+ # 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/
+* PyRTL's Sphinx build process is documented in
+ [`docs/README.md`](docs/README.md).
+* PyRTL's release process is documented in
+ [`release/README.md`](release/README.md).
+
+### Using PyRTL
+
+We love to hear from users about their projects, and if there are issues we
+will try our best to push fixes quickly. You can read more about how we have
+been using it in our research at UCSB both in simulation and on FPGAs in [our
+PyRTL paper at FPL](http://www.cs.ucsb.edu/~sherwood/pubs/FPL-17-pyrtl.pdf).
### Related Projects
-It is always important to point out that PyRTL builds on the ideas of several other related projects as we all share the common goal of trying to make hardware design a better experience! You can read more about those relationships on our [PyRTL project web page](http://ucsbarchlab.github.io/PyRTL/).
+
+It is always important to point out that PyRTL builds on the ideas of several
+other related projects as we all share the common goal of trying to make
+hardware design a better experience! You can read more about those
+relationships on our [PyRTL project web
+page](http://ucsbarchlab.github.io/PyRTL/).
diff --git a/docs/images/gcd-graph.png b/docs/images/gcd-graph.png
new file mode 100644
index 0000000000000000000000000000000000000000..f8985ff9d2e5ab6fcdacdbb96b00e4eb7f13e6d7
GIT binary patch
literal 85012
zcmZ5{1yq|sw=ER+;!Y{
cZY)&0C2pBbpWlgVz5|Tz@G>uhM%WK3M
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