merged with master

.github/workflows/pytest.yml

@@ -5,7 +5,7 @@ on: [push]
 jobs:
   SpyDrNet_push:
     name: SpyDrNet Push
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     strategy:
       matrix:
         python-version:
@@ -17,7 +17,7 @@ jobs:
     steps:
     - uses: actions/checkout@master
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Run Pytest for SpyDrNet

RELEASE.rst

@@ -1,3 +1,29 @@
+SpyDrNet 1.12.2
+----------------
+April 18, 2023
+
+Bug fix for Verilog parser for partially connected ports being misaligned and fixed primitive name with a space at the end.
+Changed some of the os.path to pathlib to conform to updated coding standards
+
+SpyDrNet 1.12.1
+----------------
+February 2, 2023
+
+* Bug fix for names in EDIF netlists in which they were cut off if more than 100 characters long. Now the allowed number of characters in a name is 255.
+* Slight additions to documentation about doing a release 
+* Removing Travis CI (from now on only Github Actions will do automated testing)
+* Fixed bug where architecture liraries were not included in the release
+
+SpyDrNet 1.12.0
+----------------
+November 9, 2022
+
+* Major improvements and fixes for the Verilog netlist parser and composer to broaden support and accuracy
+* Built in primitive libraries to allow SpyDrNet to populate port directions of primitives when parsing netlist types that don't always explicitly define primitive cells (Verilog, EBLIF). An option is added to parsing to specify which primitive library to use.
+* Improvements, fixes, and simplification to EBLIF netlist parser and composer
+* Verilog parser and composer option to remove/add lagging space in names
+* Documentation updates and improvements 
+
 SpyDrNet 1.11.1
 ---------------
 April 20, 2022

docs/source/conf.py

@@ -77,7 +77,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -164,7 +164,7 @@
      'BYU Configurable Computing Lab', 'manual'),
 ]
 
-latex_appendices = ['tutorial']
+latex_appendices = ['overview/tutorial','overview/start']
 
 # -- Options for manual page output ------------------------------------------
 

docs/source/developer/contribute.rst

@@ -8,14 +8,14 @@ This section aims to help you do a spydrnet release, meaning you make the latest
 
 1. Merge each contributors' branches into one branch (the 'next_release' branch)
 2. run `git merge master` while the next-release branch is checked out.
-3. :ref:`update_release_notes`
+3. :ref:`update_release_notes` (remember to commit and push afterwards).
 4. :ref:`update_documentation` and ensure it can build properly
 5. On Github, create a pull request with the updated code in the next_release branch.
 6. Accept and merge the pull request when the checks have finished.
 7. Move to the master branch using `git checkout master`
 8. :ref:`create_and_update_tag`
-9. :ref:`build_documentation`
-10. :ref:`build_package` (this will update the documentation’s version number)
+9. :ref:`build_package` (this will update the documentation's version number)
+10. :ref:`build_documentation`
 11. :ref:`publish_packages`
 12. :ref:`github_release`
 13. :ref:`publish_documentation`
@@ -90,23 +90,6 @@ If you mess up, you can use the following instructions to force update your tag
 
 >>> git push --tags -f
 
-.. _build_documentation:
-
-Build the Documentation
-------------------------
-
-Make sure you are in the docs directory
-
->>> cd docs
-
-then run the following:
-
->>> make clean
->>> make latexpdf
->>> make html
-
-Make sure that each one executes without errors. Try to minimize warnings as well, although the most important thing is that the documentation looks the way you want it to.
-
 .. _build_package:
 
 Build the Python Package
@@ -130,6 +113,23 @@ The build files will be stored in the following directories
 
 spydrnet/build and spydrnet/dist
 
+.. _build_documentation:
+
+Build the Documentation
+------------------------
+
+Make sure you are in the docs directory
+
+>>> cd docs
+
+then run the following:
+
+>>> make clean
+>>> make latexpdf
+>>> make html
+
+Make sure that each one executes without errors. Try to minimize warnings as well, although the most important thing is that the documentation looks the way you want it to.
+
 .. _publish_packages:
 
 Publish the Packages to Pypi

docs/source/index.rst

@@ -12,7 +12,7 @@
    :maxdepth: 2
 
    install
-   tutorial
+   overview/index
    reference/index
    auto_examples/index
    developer/index

docs/source/overview/index.rst

@@ -0,0 +1,10 @@
+.. _overview:
+
+Tutorial
+********
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial
+   start

docs/source/overview/start.rst

@@ -0,0 +1,88 @@
+Getting Started with SpyDrNet
+=============================
+
+SpyDrNet was originally built for EDF netlist, but has since been expanded to Verilog and EBLIF netlists.
+
+* Note 
+    This guide makes references to SpyDrNet TMR
+
+Parsing
+-------
+
+**Default parsing arguments**
+
+``parse(filename, architecture=None):``
+
+filename 
+
+- Name of the file that is being parsed
+
+architecture 
+
+- Desired board architecture
+
+
+**General structure**
+
+``netlist = sdn.parse(filename, ...)``
+
+**Basic structure for Verilog netlist**
+
+``netlist = sdn.parse("filename.v", architecture=XILINX_7SERIES)``
+
+**Basic structure for EDF netlists**
+
+``netlist = sdn.parse("filename.edf")``
+
+*edf usually only needs the filename and not the other arguments*
+
+Composing
+----------
+
+**Default composing arguments**
+
+``compose(netlist, filename, voters=[], definition_list=[], write_blackbox=True, write_eblif_cname=True, defparam=False):``
+
+netlist 
+
+- Netlist that was parsed in / replicated / changed
+
+filename 
+
+- Desired output name of netlist
+
+voters 
+
+- List of voters that was created in script *this is only needed for verilog netlists*
+
+definition_list 
+
+- List of definitions to write
+
+write_blackbox 
+
+- Flag that skips writing black boxes/verilog primitives
+
+write_eblif_cname 
+
+- Flag
+
+defparam 
+
+- Flag that composes parameters in *defparam* statements instead of using #()
+
+
+**General structure**
+
+``netlist.compose(filename, ...)``
+
+**Basic structure for Verilog netlist**
+
+``netlist.compose("filename_tmr.v", voters, reinsert_space=True)``
+
+**Basic structure for EDF netlists**
+
+``netlist.compose("filename_tmr.edf")``
+
+*edf usually only needs the filename and not the other arguments*
+

docs/source/tutorial.rst → docs/source/overview/tutorial.rst

@@ -1,10 +1,10 @@
-Tutorial
-============
+Overview
+========
 
 SpyDrNet is a tool for the analysis and transformation of structural netlists. A structural netlist is a static representation of an electronic circuit. A circuit consists of a number of electrical components and their connections. Figure :numref:`fig:hierarchical_netlist` shows a graphical representation of a netlist.
 
 .. _fig:hierarchical_netlist:
-.. figure:: figures/hierarchical_netlist.*
+.. figure:: ../figures/hierarchical_netlist.*
    :align: center
 
    Hierarchical representation of a Netlist 
@@ -24,7 +24,7 @@ This flow is inspired by `LLVM`_ and `Pandoc`_. LLVM has a similar flow for comp
 .. _Pandoc: https://pandoc.org/
 
 .. _fig:flow.2:
-.. figure:: /figures/flow.*
+.. figure:: ../figures/flow.*
    :align: center
    :alt: SpyDrNet Flow
 
@@ -177,14 +177,14 @@ Instances:
 **See the following two figures to aid in understanding the SpyDrNet IR:**
 
 .. _fig:IR_2:
-.. figure:: /figures/IR.*
+.. figure:: ../figures/IR.*
     :align: center
     :alt: SpyDrNet Intermediate Representation
 
     Summary of the SpyDrNet IR 1
 
 .. _fig:IR_3:
-.. figure:: /figures/spydrnet_api_elements.png
+.. figure:: ../figures/spydrnet_api_elements.png
     :align: center
     :alt: SpyDrNet Intermediate Representation
 

docs/source/reference/archive/index.rst

@@ -0,0 +1,12 @@
+.. _archive:
+
+===========
+Archive
+===========
+
+The following is from older versions of the SpyDrNet documentation 
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction

docs/source/reference/introduction.rst → docs/source/reference/archive/introduction.rst

@@ -47,7 +47,7 @@ Netlists flow through SpyDrNet in a three step process (see :numref:`fig:flow`).
 .. _Pandoc: https://pandoc.org/
 
 .. _fig:flow:
-.. figure:: ../figures/flow.*
+.. figure:: ../../figures/flow.*
    :align: center
    :alt: SpyDrNet Flow
 
@@ -82,7 +82,7 @@ At this point, SpyDrNet features and functionality are accessible via ``sdn.<fun
 Digital designs for FPGAs are represented as netlists, a list of components and connections. Netlists come from various vendors in many different formats. SpyDrNet allows you to look at and alter a netlist in a language inspecific way. SpyDrNet parses a netlist into an intermediate represention (IR) that is designed to be easily traversed and effortlessly manipulated. SpyDrNet aims to provide the tools you need to accomplish the netlist analysis and transformation tasks you have in mind without having to reinvent the wheel. :numref:`fig:IR` shows a summary of the SpyDrNet intermediate representation (IR).
 
 .. _fig:IR:
-.. figure:: ../figures/IR.*
+.. figure:: ../../figures/IR.*
    :align: center
    :alt: SpyDrNet Intermediate Representation
 

docs/source/reference/built_in_architecture.rst

@@ -0,0 +1,19 @@
+.. _built_in_architecture:
+
+Built In FPGA Architectures
+----------------------------
+
+SpyDrNet has built in libraries for the following primitive libraries:
+
+* Xilinx 7-Series
+* F4PGA Xilinx 7-Series
+* Lattice LIFCL
+
+An optional parameter can be parsed to parse() which will tell the parser to load in the specified primitive library during parsing. This allows primitive information to be known (particularly port directions) even if though it may not be defined in the netlist (as a cell define module or a blackbox).
+
+The supported types are found under **spydrnet.util.architecture**
+
+When a built in architecture parameter is passed, the parser uses the PrimitiveLibraryReader class to load in the primitive library and populate the netlist definitions with information. See below.
+
+.. currentmodule:: spydrnet.parsers.primitive_library_reader
+.. autoclass:: PrimitiveLibraryReader 

docs/source/reference/functions/index.rst

@@ -0,0 +1,12 @@
+.. _functions:
+
+Functions (Additional Information)
+----------------------------------
+
+Included are some SpyDrNet functions that are worth highlighting:
+
+.. toctree::
+   :maxdepth: 2
+
+   uniquify
+   clone

docs/source/reference/index.rst

@@ -11,12 +11,12 @@ Reference
 
    classes/index.rst
    netlist_types
+   built_in_architecture
+   functions/index
    element_data
-   clone
-   uniquify
    NamespaceManager
    verilog_support
    eblif_support
    Callback_Framework
    extensions
-   introduction
+   archive/index

examples/README.rst

@@ -1,5 +1,7 @@
 .. _sec:examples:
 
+.. _sphx_glr_auto_examples:
+
 Examples
 ========