Merge branch 'dev' into implements-options

Author: rodrigomelo9

.github/workflows/docs.yml

@@ -2,8 +2,11 @@ name: 'docs'
 
 on:
   push:
+    paths:
+      - 'docs/**'
     branches:
-#      - main
+      - main
+      - dev
 
 jobs:
   docs:
@@ -19,4 +22,4 @@ jobs:
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/_build/html
+        publish_dir: docs/build/html

Makefile

@@ -2,6 +2,8 @@
 
 .PHONY: docs
 
+all: docs lint test
+
 docs:
 	cd docs; make html
 
@@ -15,11 +17,7 @@ test:
 
 clean:
 	py3clean .
-	cd docs; make clean
-	rm -fr build .pytest_cache
-
-submodule-init:
-	git submodule update --init --recursive
-
-submodule-update:
-	cd examples/resources; git checkout main; git pull
+	rm -fr docs/build
+	rm -fr .pytest_cache
+	rm -fr `find . -name results`
+	rm -fr `find . -name __pycache__`

docs/Makefile

@@ -1,7 +1,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = _build
+BUILDDIR      = build
 HELPERS       = $(BUILDDIR)/hdl2bit $(BUILDDIR)/prj2bit $(BUILDDIR)/bitprog
 
 help:

docs/basic.rst

@@ -4,15 +4,17 @@ Basic usage
 Project Configuration
 ---------------------
 
-The first steps involve importing the necessary module to support the desired tool and instantiating the corresponding *class*:
+The first steps involve importing the necessary module to support the desired tool and instantiating the corresponding ``class``:
 
 .. code-block:: python
 
    from pyfpga.vivado import Vivado
 
    prj = Vivado('PRJNAME', odir='OUTDIR')
 
-In the example, we are using Vivado, specifying the optional parameter *project name* (*tool name* if omitted) and *output directory* (*results* by default).
+In the example, we are using Vivado, specifying the optional parameters
+``project name`` (``tool name`` if omitted) and ``output directory``
+(``results`` by default).
 
 Next step is to specify the target FPGA device:
 
@@ -32,9 +34,8 @@ HDL source files are added using one of the following methods:
    prj.add_vlog('PATH_TO_FILES_GLOB_COMPATIBLE')
    prj.add_slog('PATH_TO_FILES_GLOB_COMPATIBLE')
 
-In these methods, you provide a path to the files. The path can include wildcards (like `*.vhdl`), allowing you to match multiple files at once.
-
-For `add_vhdl`, you can also optionally specify a library name where the files will be included.
+In these methods, you provide a path to the files. The path can include wildcards (like ``*.vhdl``), allowing you to match multiple files at once.
+In case of ``add_vhdl``, you can also optionally specify a library name where the files will be included.
 
 .. note::
 
@@ -43,6 +44,15 @@ For `add_vhdl`, you can also optionally specify a library name where the files w
   .. _glob: https://docs.python.org/3/library/glob.html
   .. _Path: https://docs.python.org/3/library/pathlib.html
 
+.. hint::
+
+   Files are processed in the order they are added. If a file is specified more than once,
+   it is removed from its previous position and placed at the end of the list.
+   This allows you to ensure that a file is processed after others when necessary
+   (e.g., placing a top-level at the end) or to customize options
+   (e.g., removing a VHDL library specification in case of a top-level)
+   when multiple files are added using a wildcard.
+
 Generics/parameters can be specified with:
 
 .. code-block:: python
@@ -82,7 +92,8 @@ After configuring the project, you can run the following to generate a bitstream
 
    prj.make()
 
-By default, this method performs *project creation*, *synthesis*, *place and route*, and *bitstream generation*.
+By default, this method performs **project creation**, **synthesis**, **place and route**,
+and **bitstream generation**.
 However, you can optionally specify both the initial and final stages, as follows:
 
 .. code-block:: python
@@ -100,7 +111,8 @@ However, you can optionally specify both the initial and final stages, as follow
 
 .. note::
 
-   After executing this method, you will find the file `<TOOL>.tcl` (or `sh` in some cases) in the output directory.
+   After executing this method, you will find the file ``<TOOL>.tcl``
+   (``<TOOL>.sh`` in some cases) in the output directory.
    For debugging purposes, if things do not work as expected, you can review this file.
 
 Bitstream programming
@@ -112,13 +124,14 @@ The final step is programming the FPGA:
 
    prj.prog('BITSTREAM', 'POSITION')
 
-Both `BITSTREAM` and `POSITION` are optional.
-If `BITSTREAM` is not specified, PyFPGA will attempt to discover it based on project information.
-The `POSITION` parameter is not always required (depends on the tool being used).
+Both ``BITSTREAM`` and ``POSITION`` are optional.
+If ``BITSTREAM`` is not specified, PyFPGA will attempt to discover it based on project information.
+The ``POSITION`` parameter is not always required (depends on the tool being used).
 
 .. note::
 
-   After executing this method, you will find the file `<TOOL>prog.tcl` (or `sh` in some cases) in the output directory.
+   After executing this method, you will find the file ``<TOOL>prog.tcl``
+   (``<TOOL>-prog.sh`` in some cases) in the output directory.
    For debugging purposes, if things do not work as expected, you can review this file.
 
 Debugging

docs/conf.py

@@ -8,8 +8,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'PyFPGA'
-copyright = '2024, Rodrigo Alejandro Melo'
-author = 'Rodrigo Alejandro Melo'
+copyright = '2016-2024, PyFPGA Project'
+author = 'PyFPGA contributors'
 
 # -- General configuration ---------------------------------------------------
 
@@ -31,9 +31,9 @@
    'repositoy': ('https://github.com/PyFPGA/pyfpga/tree/main/%s', None)
 }
 
-exclude_patterns = ['_build', 'wip']
+exclude_patterns = ['build']
 
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_static_path = ['images']

docs/extending.rst

@@ -1,40 +1,76 @@
 Extending
 =========
 
-1. Add support for the new tool:
+.. note::
 
-.. code-block:: python
+   All <TOOL> classes inherit from ``Project`` (``project.py``).
+
+This is a guide on how to add support for a new TOOL.
+
+Add support for the new tool
+----------------------------
+
+.. code-block:: bash
 
    pyfpga/templates/<NEWTOOL>.jinja
    pyfpga/templates/<NEWTOOL>-prog.jinja
    pyfpga/<NEWTOOL>.py
+   pyfpga/factory.py # UPDATE
+   pyfpga/helpers/prj2bit.py # UPDATE
 
-2. Include the new tool on Factory:
+Add tests and a tool mock-up
+----------------------------
 
-.. code-block:: python
+.. code-block:: bash
 
-   pyfpga/factory.py
+   tests/test_tools.py # UPDATE
+   tests/support.py # UPDATE if exceptions are needed
+   tests/mocks/<NEWCOMMAND>
 
-3. Add tests and a tool mock-up:
+Add examples
+------------
 
-.. code-block:: python
+.. code-block:: bash
 
-   tests/test_tools.py
-   tests/mocks/<NEWTOOL_EXECUTABLE>
+   examples/sources/cons/<NEWBOARD>/timing.<EXT>
+   examples/sources/cons/<NEWBOARD>/clk.<EXT>
+   examples/sources/cons/<NEWBOARD>/led.<EXT>
+   examples/projects/<NEWTOOL>.py
+   examples/projects/regress.sh # UPDATE
+   examples/helpers/<NEWTOOL>.sh
+   examples/hooks/<NEWTOOL>.py # OPTIONAL
 
-4. Updated the project's documentation:
+Verify the code
+---------------
 
-.. code-block:: python
+Run it at the root of the repo.
 
-   README.md
-   docs
+.. code-block:: bash
 
-5. [OPTIONAL] Add examples:
+   make docs
+   make lint
+   make test
 
-.. code-block:: python
+.. tip::
 
-   examples/sources/cons/<NEWBOARD>/timing.<EXT>
-   examples/sources/cons/<NEWBOARD>/clk.<EXT>
-   examples/sources/cons/<NEWBOARD>/led.<EXT>
-   examples/projects/<NEWTOOL>.py
-   examples/hooks/<NEWTOOL>.py
+   You can simply run ``make`` to perform all the operations.
+   Running ``make clean`` will remove all the generated files.
+
+Verify the functionality
+------------------------
+
+.. code-block:: bash
+
+   cd examples/projects/
+   bash regress.sh <NEWTOOL>
+   cd ../../tests/
+   python3 support.py --tool <NEWTOOL>
+
+Updated the documentation
+-------------------------
+
+.. code-block:: bash
+
+   README.md
+   docs/intro.rst
+   docs/tools.rst

docs/helpers.rst

@@ -4,14 +4,14 @@ Helpers
 hdl2bit
 -------
 
-.. literalinclude:: _build/hdl2bit
+.. literalinclude:: build/hdl2bit
 
 prj2bit
 -------
 
-.. literalinclude:: _build/prj2bit
+.. literalinclude:: build/prj2bit
 
 bitprog
 -------
 
-.. literalinclude:: _build/bitprog
+.. literalinclude:: build/bitprog

docs/images/Makefile

@@ -0,0 +1,15 @@
+#!/usr/bin/make
+
+FILES  = $(wildcard *.dot)
+FILES := $(basename $(FILES))
+FILES := $(addsuffix .svg,$(FILES))
+
+ODIR = .
+
+vpath %.svg $(ODIR)
+
+%.svg: %.dot
+	@mkdir -p $(ODIR)
+	dot -Tsvg $< -o $(ODIR)/$@
+
+all: $(FILES)

docs/_static/logo.png renamed to docs/images/logo.png

@@ -0,0 +1,28 @@
+digraph openflow {
+  graph [ranksep=0.25];
+  node [shape = doublecircle];
+  node [shape = rectangle];
+  GHDL "ghdl-yosys-plugin" Yosys "nextpnr-ice40" "nextpnr-ecp5" icetime icepack iceprog eccpack;
+  node [shape = note ];
+  VHDL Verilog;
+  node [shape = box3d ];
+  ice40;
+  node [shape = oval];
+  "bit-ice40" [label=".bit"];
+  "bit-ecp5"  [label=".bit"];
+  VHDL                -> {GHDL "ghdl-yosys-plugin"};
+  GHDL                -> "ghdl-yosys-plugin";
+  "ghdl-yosys-plugin" -> Yosys;
+  Verilog             -> Yosys;
+  Yosys               -> ".json";
+  ".json"             -> {"nextpnr-ice40" "nextpnr-ecp5"};
+  "nextpnr-ice40"     -> ".asc";
+  "nextpnr-ecp5"      -> ".config";
+  ".asc"              -> {icetime icepack};
+  icepack             -> "bit-ice40";
+  "bit-ice40"         -> iceprog;
+  iceprog             -> ice40;
+  ".config"           -> eccpack;
+  eccpack             -> "bit-ecp5";
+  {rank = same; GHDL ; "ghdl-yosys-plugin"; Yosys;}
+}