Update python to 3.12 and update documentation (#229)

* doc: fix typo

* doc: fix note about FASM warning and typos

* doc: fix more layout issues in Usage.rst

* fix: update python version to python3.12

* doc: add copybutton module and regex for prompts to be ignored when copying

* doc: Fix minor issue resulting in errors when building the docs, also add prompts to more commands

* doc: add recommendation for using the OSS CAD Suite and a note about the minimum required Ubuntu version for installing Yosys and nextpnr using apt

* fix: remove check for python version in FABulous.py

.github/workflows/fabric_gen.yml

@@ -10,10 +10,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: recursive
-      - name: Set up Python 3.10
+      - name: Set up Python 3.12
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: "3.12"
       - name: Set up OSS CAD suite
         uses: YosysHQ/setup-oss-cad-suite@v2
       - name: Install dependencies

FABulous/FABulous.py

@@ -1542,9 +1542,6 @@ def main():
     -v, --verbose : bool, optional
         Show detailed log information including function and line number.
     """
-    if sys.version_info < (3, 9, 0):
-        logger.critical("Need Python 3.9 or above to run FABulous")
-        exit(-1)
     parser = argparse.ArgumentParser(
         description="The command line interface for FABulous"
     )

README.md

@@ -1,7 +1,7 @@
 # FABulous: an Embedded FPGA Framework
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Python](https://img.shields.io/badge/Python-3.9-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org)
+[![Python](https://img.shields.io/badge/Python-3.12-3776AB.svg?style=flat&logo=python&logoColor=white)](https://www.python.org)
 [![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 ## Introduction
@@ -38,14 +38,25 @@ Dirk Koch, Nguyen Dao, Bea Healy, Jing Yu, and Andrew Attwood. 2021. FABulous: A
 
 The following packages need to be installed for generating fabric HDL models and using the FABulous front end:
 
-- Python 3.9 or later
+- Python 3.12 or later
 
 Install python dependencies
 
 ```
 sudo apt-get install python3-tk python3-virtualenv
 ```
 
+> [!NOTE]
+>
+>If you get the warning `ModuleNotFoundError: No module named 'tkinter'` or
+>errors when installing the requirements, you have to install the dependencies
+>for your specific python version. For Python 3.12 use
+>
+>```
+>sudo apt-get install python3.12-tk python3.12-virtualenv
+>```
+
+
 The following packages need to be installed for the CAD toolchain
 
 - [Yosys](https://github.com/YosysHQ/yosys)

docs/environment.yml

@@ -3,7 +3,7 @@ channels:
 - conda-forge
 - defaults
 dependencies:
-- python>=3.8
+- python>=3.12
 - pip
 - pip:
   - -r ./requirements.txt

docs/source/FPGA-to-bitstream/Bitstream generation.rst

@@ -38,7 +38,7 @@ With the FASM file generated by Nextpnr, you can run this command for bitstream
         (venv)$ bit_gen -genBitstream <fasm_file> meta_data.txt <bitstream file>
 
 +------------------+-----------------------------------------------------------------------+
-| <fasm_file>      | the FASM file generated by Nextpnr in previous compilation     |
+| <fasm_file>      | the FASM file generated by Nextpnr in previous compilation            |
 +------------------+-----------------------------------------------------------------------+
 | <bitstream_file> | User can define the output binary file name with ``.bin`` format      |
 +------------------+-----------------------------------------------------------------------+

docs/source/FPGA-to-bitstream/Nextpnr compilation.rst

@@ -19,7 +19,7 @@ To generate the FASM file using nextpnr, run the following command:
 
 .. code-block:: console
 
-        FAB_ROOT=<Project_directory> nextpnr-generic --uarch fabulous --json <JSON_file> -o fasm=<output_FASM_file>
+        $ FAB_ROOT=<Project_directory> nextpnr-generic --uarch fabulous --json <JSON_file> -o fasm=<output_FASM_file>
 
 
 +---------------------+------------------------------------------------+
@@ -32,7 +32,7 @@ Example,
 
 .. code-block:: console
         
-        FAB_ROOT=demo nextpnr-generic --uarch fabulous --json demo/user_design/sequential_16bit_en.v -o fasm=demo/user_design/sequential_16bit_en.fasm
+        $ FAB_ROOT=demo nextpnr-generic --uarch fabulous --json demo/user_design/sequential_16bit_en.v -o fasm=demo/user_design/sequential_16bit_en.fasm
 
 Primitive instantiation
 -----------------------

docs/source/FPGA-to-bitstream/Yosys compilation.rst

@@ -23,7 +23,7 @@ calling the following command:
 .. code-block:: console
 
         # Nextpnr backend synthesis (JSON)
-        synthesis <path_to_user_design>
+        FABulous> synthesis <path_to_user_design>
         
 
 

docs/source/FPGA_CAD-tools/index.rst

@@ -8,4 +8,3 @@ FPGA CAD-tool parameterization
 
    yosys
    nextpnr
-   vpr

docs/source/Usage.rst

@@ -11,14 +11,24 @@ The following packages need to be installed for generating fabric HDLs
 
 :Python:
 
-Version >= 3.9
+Version >= 3.12
 
 :Dependencies:
 
 .. code-block:: console
 
     $ sudo apt-get install python3-tk python3-virtualenv
 
+.. note::
+
+    If you get the warning ``ModuleNotFoundError: No module named 'tkinter'``
+    or errors when installing the requirements, you have to install the
+    dependencies for your specific python version. For Python 3.12 use
+
+    .. code-block:: console
+
+       $ sudo apt-get install python3.12-tk python3.12-virtualenv
+
 :FABulous repository:
 
 .. code-block:: console
@@ -29,13 +39,13 @@ Version >= 3.9
 
 We recommend using python virtual environments for the usage of FABulous.
 If you are not sure what this is and why you should use it, please read the
-:`virtualenv documentation <https://virtualenv.pypa.io/en/latest/index.html>`_:
+`virtualenv documentation <https://virtualenv.pypa.io/en/latest/index.html>`_.
 
 .. code-block:: console
 
    $ cd FABulous
-    $ virtualenv venv
-    $ source venv/bin/activate
+   $ virtualenv venv
+   $ source venv/bin/activate
 
 Now there is a ``(venv)`` at the beginning of your command prompt.
 You can deactivate the virtual environment with the ``deactivate`` command.
@@ -49,15 +59,28 @@ with ``source venv/bin/activate`` to use FABulous.
     (venv)$ pip install -r requirements.txt
 
 
-The following packages need to be installed for the CAD toolchain
+The following packages need to be installed for the CAD toolchain:
+
 
 :`Yosys <https://github.com/YosysHQ/yosys>`_:
  version > 0.26+0
 
 :`Nextpnr-generic <https://github.com/YosysHQ/nextpnr#nextpnr-generic>`_:
  version > 0.4-28-gac17c36b
 
+.. note::
+
+   We recommend using the `OSS CAD Suite
+   <https://github.com/YosysHQ/oss-cad-suite-build>`_ to
+   install the packages.
+
+   If you just want to install Yosys using **apt**, make
+   sure you have at least Ubuntu 23.10 (24.04 for the LTS
+   versions) installed to meet the above requirement.
+
+
 Install FABulous with "editable" option:
+
 .. code-block:: console
 
     (venv)$ pip install -e .
@@ -76,47 +99,46 @@ Building Fabric and Bitstream
    FABulous> run_FABulous_fabric
    FABulous> run_FABulous_bitstream npnr user_design/sequential_16bit_en.v
 
-.. note:
-  You will probably recieve a Warning for the FASM package like the following:
+.. note::
+
+  You will probably receive a warning for the FASM package like the following:
+      .. code-block:: text
   
-  ```
-  RuntimeWarning: Unable to import fast Antlr4 parser implementation.
-  ImportError: cannot import name 'antlr_to_tuple' from partially initialized module 'fasm.parser' (most likely due to a circular import)
+          RuntimeWarning: Unable to import fast Antlr4 parser implementation.
+          ImportError: cannot import name 'antlr_to_tuple' from partially initialized module 'fasm.parser' (most likely due to a circular import)
 
-  Falling back to the much slower pure Python textX based parser
-  implementation.
+          Falling back to the much slower pure Python textX based parser
+          implementation.
 
-  Getting the faster antlr parser can normally be done by installing the
-  required dependencies and then reinstalling the fasm package with:
-    pip uninstall
-    pip install -v fasm
+          Getting the faster antlr parser can normally be done by installing the
+          required dependencies and then reinstalling the fasm package with:
+            pip uninstall
+            pip install -v fasm
 
-  ```
-  
-  This usually happens when FASM can't find the Antlr4 package, but this is not mendatory for us.
+  This usually happens when FASM can't find the Antlr4 package, but this is not mandatory for us.
   If you still want to fix this issue, you have to install FASM in your virtual environment from source.
-  Please have a look at the :`FASM documentation <https://github.com/chipsalliance/fasm>`_ for more information.
+  Please have a look at the `FASM documentation <https://github.com/chipsalliance/fasm>`_ for more information.
 
 After a successful call with the command ``run_FABulous_fabric`` the RTL file of each of the tiles can be found in the ``Tile`` folder and the fabric RTL file can be found in the ``Fabric`` folder.
 
 After a successful call with the command ``run_FABulous_bitstream user_design/sequential_16bit_en.v``.
 The bitstream and all the log files generated during synthesis and place and route can be found under
-the ``user_design`` folder. The bitstream will be named as ``sequential_16bit_en.bin``
+the ``user_design`` folder. The bitstream will be named as ``sequential_16bit_en.bin``.
 
 Running in a Docker container
 -----------------------------
 
 Within the FABulous repo we provide a Dockerfile that allows users to run the FABulous flow within a Docker container, installing all requirements automatically.
 
-:Setting up the Docker environment:
+**Setting up the Docker environment**
 
 To set up the Docker environment, navigate to the FABulous root directory and run:
 
 .. code-block:: console
 
      $ docker build -t fabulous .
 
-:Running the Docker environment:
+**Running the Docker environment**
 
 To run the Docker environment, stay in the FABulous root directory (this is vital as the command mounts the current directory as the container's filesystem) and run:
 

docs/source/conf.py

@@ -23,6 +23,7 @@
     "sphinxcontrib.bibtex",
     "sphinx.ext.napoleon",
     "sphinx-prompt",
+    "sphinx_copybutton",
 ]
 
 intersphinx_mapping = {
@@ -82,3 +83,5 @@
 epub_show_urls = "footnote"
 
 bibtex_bibfiles = ["publications.bib"]
+copybutton_prompt_text = r"\$ |FABulous> |\(venv\)\$ "
+copybutton_prompt_is_regexp = True

docs/source/fabric_definition.rst

@@ -247,7 +247,6 @@ The ``INCLUDE`` keyword specifies a path to another tile configuration, and the
 entry within the target path will be appended to the file. For example if ``../include/Base.csv`` contains:
 
 .. code-block:: python
-   :emphasize-lines: 1,12
 
    NORTH,      N2BEG,       0,        2,        N2END,            8
    JUMP,       J2_BEG,      0,        0,        J2_END,           12

pyproject.toml

@@ -7,7 +7,7 @@ name = "FABulous-FPGA"
 authors = [{name = "Jing, Nguyen, Bea, Bardia, Dirk", email = "[email protected]"}]
 description = "FABulous FPGA Fabric generator"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.12"
 dynamic = ["version"]
 
 classifiers = [