Update documentation

.github/workflows/Pipeline.yml

@@ -107,11 +107,11 @@ jobs:
         uses: actions/checkout@v3
 
       - name: 🔧 Prepare environment
-        run: ./.github/scripts/prepare_environment.sh
+        run: ./scripts/prepare_environment.sh
 
       - name: 🐍 Install f4pga (pip)
         run: |
-          . ./.github/scripts/activate.sh
+          . ./scripts/activate.sh
           cd f4pga
           pip install .
           cd ..
@@ -124,7 +124,7 @@ jobs:
       - name: 🚧 [F4PGA] Test f4pga build
         if: matrix.flow == 'F4PGA'
         run: |
-          . ./.github/scripts/activate.sh
+          . ./scripts/activate.sh
           cd f4pga-examples/${{ matrix.fam }}
           f4pga -vv build --flow ../../.github/${{ matrix.fam }}_test.json
 
@@ -141,7 +141,7 @@ jobs:
       - name: 🚧 [SymbiFlow] Test make example
         if: matrix.flow == 'SymbiFlow'
         run: |
-          . ./.github/scripts/activate.sh
+          . ./scripts/activate.sh
           cd f4pga-examples/${{ matrix.fam }}
           export F4PGA_USE_DEPRECATED=true
           case '${{ matrix.fam }}' in
@@ -179,18 +179,18 @@ jobs:
         uses: actions/checkout@v3
 
       - name: 🔧 Prepare environment
-        run: ./.github/scripts/prepare_environment.sh
+        run: ./scripts/prepare_environment.sh
 
       - name: 🐍 Install f4pga (pip)
         run: |
-          . ./.github/scripts/activate.sh
+          . ./scripts/activate.sh
           cd f4pga
           pip install .
           cd ..
 
       - name: 🚦 Test Python wrappers
         run: |
-          . ./.github/scripts/activate.sh
+          . ./scripts/activate.sh
           pip3 install -r ./test/requirements.txt
           pytest --verbose --capture=no -rA --color=yes test/
 

README.md

@@ -1,58 +1,23 @@
-# FOSS Flows For FPGA (F4PGA) project
-
 <p align="center">
   <a title="Website" href="https://f4pga.org"><img src="https://img.shields.io/website?longCache=true&style=flat-square&label=f4pga.org&up_color=10cfc9&url=https%3A%2F%2Ff4pga.org%2Findex.html&labelColor=fff"></a><!--
   -->
-  <a title="Community" href="https://f4pga.readthedocs.io/en/latest/community.html#communication"><img src="https://img.shields.io/badge/Chat-IRC%20%7C%20Slack-white?longCache=true&style=flat-square&logo=Slack&logoColor=fff"></a><!--
+  <a title="Documentation" href="https://f4pga.readthedocs.io"><img src="https://img.shields.io/website?longCache=true&style=flat-square&label=Documentation&up_color=1226aa&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff"></a><!--
   -->
-  <a title="'Automerge' workflow status" href="https://github.com/chipsalliance/f4pga/actions/workflows/Doc.yml"><img alt="'Automerge' workflow status" src="https://img.shields.io/github/workflow/status/chipsalliance/f4pga/Automerge/main?longCache=true&style=flat-square&label=Tests&logo=Github%20Actions&logoColor=fff"></a><!--
+  <a title="Community" href="https://f4pga.readthedocs.io/en/latest/community.html#communication"><img src="https://img.shields.io/badge/Chat-IRC%20%7C%20Slack-white?longCache=true&style=flat-square&logo=Slack&logoColor=fff"></a><!--
   -->
 </p>
 
-This is the top-level repository for the [F4PGA](https://f4pga.org/) project, which is a Workgroup under the [CHIPS Alliance](https://chipsalliance.org).
-The elements of the project include (but are not limited to):
-
-* The F4PGA open source FPGA toolchains for programming FPGAs (formerly known as [SymbiFlow](https://github.com/SymbiFlow)).
-  This includes:
-
-  * [![Documentation](https://img.shields.io/website?longCache=true&style=flat-square&label=Documentation&up_color=1226aa&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga.readthedocs.io)
-  * F4PGA Architecture Definitions [![Arch-Defs (for Developers)](https://img.shields.io/website?longCache=true&style=flat-square&label=For%20Developers&up_color=231f20&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga.readthedocs.io%2Fprojects%2Farch-defs%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga.readthedocs.io/projects/arch-defs)
-  * F4PGA Examples [![Examples (for Users)](https://img.shields.io/website?longCache=true&style=flat-square&label=For%20Users&up_color=231f20&up_message=%E2%9E%9A&url=https%3A%2F%2Ff4pga-examples.readthedocs.io%2Fen%2Flatest%2Findex.html&labelColor=fff)](https://f4pga-examples.readthedocs.io)
-  * [F4PGA Yosys plugins](https://github.com/chipsalliance/yosys-f4pga-plugins)
-
-* The FPGA interchange format (an interchange format defined by CHIPS Alliance to enable interoperability between
-  different FPGA tools) adopted by the F4PGA toolchain:
-
-  * [FPGA Interchange schema](https://github.com/chipsalliance/fpga-interchange-schema)
-  * [FPGA Interchange Python utilities](https://github.com/chipsalliance/python-fpga-interchange)
-  * [FPGA Interchange Test suite](https://github.com/SymbiFlow/fpga-interchange-tests)
-
-* The [FPGA tool performance framework](https://github.com/chipsalliance/fpga-tool-perf) framework for benchmarking
-  designs against various FPGA tools, and vice versa, over time.
-
-* FPGA Database visualisation tools for visual exploration of FPGA bitstream and databases:
-
-  * [F4PGA bitstream viewer](https://github.com/SymbiFlow/f4pga-bitstream-viewer)
-  * [F4PGA database visualizer](https://github.com/chipsalliance/f4pga-database-visualizer)
-
-* Other utilities (FPGA assembly format, documentation and other):
-
-  * [F4PGA Assembly (FASM)](https://github.com/chipsalliance/fasm)
-  * [Xilinx bitstream generation library](https://github.com/SymbiFlow/f4pga-xc-fasm)
-  * [Verilog-to-routing XML utilities](https://github.com/SymbiFlow/vtr-xml-utils)
-  * [SDF format utilities](https://github.com/chipsalliance/python-sdf-timing)
-  * [F4PGA tools data manager](https://github.com/SymbiFlow/symbiflow-tools-data-manager)
-  * [F4PGA Sphinx Theme](https://github.com/SymbiFlow/sphinx_symbiflow_theme)
-  * [F4PGA Sphinx HDL diagrams](https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams)
-  * [F4PGA Sphinx Verilog domain](https://github.com/SymbiFlow/sphinx-verilog-domain)
+# FOSS Flows For FPGA (F4PGA) project
 
-## F4PGA Workgroup
+<p align="center">
+  <a title="'Automerge' workflow status" href="https://github.com/chipsalliance/f4pga/actions/workflows/Doc.yml"><img alt="'Automerge' workflow status" src="https://img.shields.io/github/workflow/status/chipsalliance/f4pga/Automerge/main?longCache=true&style=flat-square&label=Tests&logo=Github%20Actions&logoColor=fff"></a><!--
+  -->
+</p>
 
-The F4PGA Workgroup consists of members from different backgrounds, including FPGA vendors
-([Xilinx](https://www.xilinx.com/) and [QuickLogic](https://www.quicklogic.com/)),
-industrial users
-([Google](https://www.google.com/), [Antmicro](https://antmicro.com/))
-and academia
-([University of Toronto](https://www.utoronto.ca/)),
+This is the top-level repository for the [F4PGA](https://f4pga.org/) project, which is a Workgroup under the [CHIPS Alliance](https://chipsalliance.org); consisting of members from different backgrounds, including FPGA vendors, industrial users and academia (see [Documentation > Community](https://f4pga.readthedocs.io/en/latest/community.html));
 who collaborate to build a more open source and software-driven FPGA ecosystem (IP, tools and workflows) to drive the
 adoption of FPGAs in existing and new use cases, and eliminate barriers of entry.
+
+* [Documentation > Getting started](https://f4pga.readthedocs.io) (for everyone)
+* [F4PGA Examples](https://f4pga-examples.readthedocs.io) (for users)
+* [F4PGA Architecture Definitions](https://f4pga.readthedocs.io/projects/arch-defs) (for developers)

docs/changes.yml

@@ -37,7 +37,7 @@
         - symbiflow-ql-eos-s3_wlcsp-*-tar-xz
   description: |
     * Tarballs from f4pga-arch-defs now include usable environment and requirements files which allow bootstraping
-    minimal Conda environments.
+      minimal Conda environments.
 
     * The default F4PGA_SHARE_DIR path does not include subdir 'install' by default.
 

docs/conf.py

@@ -171,8 +171,11 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
+    "examples": ("https://f4pga-examples.readthedocs.io/en/latest/", None),
     "arch-defs": ("https://f4pga.readthedocs.io/projects/arch-defs/en/latest/", None),
+    "conda-eda": ("https://hdl.github.io/conda-eda/", None),
     "constraints": ("https://hdl.github.io/constraints/", None),
+    "containers": ("https://hdl.github.io/containers/", None),
     "fasm": ("https://fasm.readthedocs.io/en/latest/", None),
     "interchange": ("https://fpga-interchange-schema.readthedocs.io/", None),
     "openfpgaloader": ("https://trabucayre.github.io/openFPGALoader/", None),
@@ -189,5 +192,5 @@
    'ghsharp':   ('https://github.com/chipsalliance/f4pga/issues/%s', '#'),
    'ghissue':   ('https://github.com/chipsalliance/f4pga/issues/%s', 'issue #'),
    'ghpull':    ('https://github.com/chipsalliance/f4pga/pull/%s', 'pull request #'),
-   'ghsrc':     ('https://github.com/chipsalliance/f4pga/blob/master/%s', '')
+   'ghsrc':     ('https://github.com/chipsalliance/f4pga/blob/main/%s', '')
 }

docs/getting-started.rst

@@ -1,23 +1,142 @@
 Getting started
 ###############
 
-To begin using F4PGA, you might want to take a look at the tutorials below, which make for a good starting point.
-They will guide you through the process of using the toolchain, explaining how to generate and load a bitstream into
-your FPGA.
+To begin using F4PGA, you might want to take a look at the :ref:`GettingStarted:Guidelines` below, which make for a good
+starting point.
+They will guide you through the process of installing and using the flows, explaining how to generate and load a
+bitstream into your FPGA.
 
-* `Examples ➚ <https://f4pga-examples.readthedocs.io>`__ (for users)
+F4PGA flows are composed of multiple tools, scripts and CLI utilities.
+Fortunately, various alternatives exist for setting up the whole ecosystem without going through the daunting task of
+installing pieces one-by-one.
+See :ref:`GettingStarted:ToolchainInstallation` below.
 
-* `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs/en/latest/getting-started.html>`__ (for developers)
+.. _GettingStarted:Guidelines:
 
-  * `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__
+Guidelines
+==========
 
-  * `Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>`__
+This is the main documentation, which gathers info about the :ref:`Python CLI tools and APIs <pyF4PGA>` and the
+:ref:`Desing Flows <Flows>` supported by F4PGA, along with a :ref:`Glossary`, references to specifications, plugins and
+:ref:`publications <References>`.
 
-    * `X-Ray Quickstart ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide>`__
+Since F4PGA is meant for users with varying backgrounds and expertise, three paths are provided to walk into the ecosystem.
 
-  * `Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>`__
+**Newcomers** are invited to go through `Examples ➚ <https://f4pga-examples.readthedocs.io>`__, which provides
+step-by-step guidelines to install the tools through `Conda ➚ <https://conda.io>`__, generate a bitstream from one of the
+provided designs and load the bitstream into a development board.
+See :ref:`examples:CustomizingMakefiles` for adapting the build plumbing to your own desings.
 
-  * :gh:`Project Icestorm ➚ <f4pga/icestorm>`
+For **Intermediate** users and contributors, who are already familiar with installing the tools and building bitstreams,
+it is recommended to read the shell scripts in subdir :ghsrc:`scripts`, as well as the Continuous Integration
+:ghsrc:`Pipeline <.github/workflows/Pipeline.yml>`.
+Moreover, workflow `containers-conda-f4pga.yml <https://github.com/hdl/packages/blob/main/.github/workflows/containers-conda-f4pga.yml>`__
+in :gh:`hdl/packages` shows how to use the ``*/conda/f4pga/*`` containers from :gh:`hdl/containers`
+(see `workflow runs <https://github.com/hdl/packages/actions/workflows/containers-conda-f4pga.yml>`__ and
+:ref:`GettingStarted:ToolchainInstallation:Other:Containers`).
+
+**Advanced** users and developers willing to support new devices and/or enhance the features of the supported families
+(see `F4PGA Architectures Visualizer ➚ <https://chipsalliance.github.io/f4pga-database-visualizer/>`__)
+should head to `Architecture Definitions ➚ <https://f4pga.readthedocs.io/projects/arch-defs>`__.
+The effort to document the details of each device/family are distributed on multiple projects:
+
+* `Project X-Ray ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/>`__
+
+  * `X-Ray Quickstart ➚ <https://f4pga.readthedocs.io/projects/prjxray/en/latest/db_dev_process/readme.html#quickstart-guide>`__
+
+* `Project Trellis ➚ <https://prjtrellis.readthedocs.io/en/latest/>`__
+
+* :gh:`Project Icestorm ➚ <f4pga/icestorm>`
+
+
+.. _GettingStarted:ToolchainInstallation:
+
+Toolchain installation
+======================
+
+F4PGA flows require multiple radpidly moving tools, assets and scripts, which makes it difficult for system packagers to
+catch up.
+Although some of the tools used in F4PGA (such as yosys, nextpnr or vpr) are available already through ``apt``, ``dnf``,
+``pacman``, etc. they typically use pinned versions which are not the latest.
+Therefore, the recommended installation procedure to follow the guidelines in F4PGA is repositories is using `Conda ➚ <https://conda.io>`__,
+or some other pre-packaged solution combining latest releases.
+
+
+.. _GettingStarted:ToolchainInstallation:Conda:
+
+Conda (Recommended)
+-------------------
+
+.. IMPORTANT::
+  Dure to size constraints, Architecture Definition packages cannot be distributed through Conda.
+  Hence, installing a functional F4PGA system is a two step process: bootstraping the conda environment and getting the
+  tarballs (or vice versa).
+  In the future, getting and managing the tarballs might be handled by F4PGA.
+
+In coherence with the :ref:`GettingStarted:Guidelines` above, multiple Conda environments are provided:
+
+* **Newcomers** will find environment and requirements files in :gh:`chipsalliance/f4pga-examples`, which are to be used
+  as explained in :ref:`examples:Getting`.
+
+* **Intermediate** users and contributors can use the minimal environment and requirements files included in the
+  Architecture Definition packages, as is done in the CI of this repository.
+
+* **Advanced** users and developers will get all the dependencies by bootstraping the environment in :gh:`SymbiFlow/f4pga-arch-defs`.
+
+Summarizing, the installation procedure implies:
+
+* Setting environment variables ``F4PGA_INSTALL_DIR`` and ``F4PGA_FAM`` (and optionally ``F4PGA_SHARE_DIR``), so that
+  CLI utilities can find tools and assets.
+* Downloading and extracting the Architecture Definition tarballs.
+* Getting the environment and requirements files, by cloning f4pga-examples or f4pga-arch-defs, or by using the ones
+  included in the tarballs.
+* Bootstraping the Conda environment and optionally installing additional tools.
+
+.. NOTE::
+  Architecture Definition packages are built and released in :gh:`SymbiFlow/f4pga-arch-defs`.
+  In this repository and in :gh:`chipsalliance/f4pga-examples`, pinned versions of the packages are used.
+  However, tracking the *latest* release is also supported.
+  See :ref:`arch-defs:Packages`.
+
+
+.. _GettingStarted:ToolchainInstallation:Conda:Bumping:
+
+Bumping/overriding specific tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Find guidelines to tweak the Conda environment and to override specific tools at :ref:`conda-eda:Usage:Bumping`.
+
+In order to bump the Architecture Definition packages to an specific version, check the TIMESTAMP and the commit hash in
+the job named ``GCS`` in a successful run of workflow :gh:`Automerge <SymbiFlow/f4pga-arch-defs/actions/workflows/Automerge.yml>`
+on branch ``main`` of :gh:`SymbiFlow/f4pga-arch-defs`.
+Alternatively, use the latest as explained in :ref:`arch-defs:Packages`.
+
+
+.. _GettingStarted:ToolchainInstallation:Other:
+
+Other
+-----
+
+Apart from Conda, multiple other solutions exist for setting up all the tools required in F4PGA.
+:gh:`hdl/packages` *is an index for several projects providing great prepackaged/prebuilt and easy-to-set-up
+bleeding-edge packages/environments of electronic design automation (EDA) tools/projects*.
+
+
+.. _GettingStarted:ToolchainInstallation:Other:Containers:
+
+Containers
+~~~~~~~~~~
+
+Ready-to-use docker/podman containers are maintained in :gh:`hdl/containers` and made available through
+`gcr.io/hdl-containers` or `ghcr.io/hdl/containers`.
+Some of those include Conda, the Architecture Definitions and the f4pga Python package, so they are ready to use along
+with the examples in :gh:`chipsalliance/f4pga-examples`.
+See :ref:`containers:tools-and-images:f4pga`.
+
+.. HINT::
+  :ghsharp:`574` is work in progress to provide an F4PGA Action
+  (see `Understanding GitHub Actions <https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions>`__)
+  based on ``*/conda/f4pga/*`` containers.
 
 
 .. _GettingStarted:LoadingBitstreams:

docs/glossary.rst

@@ -1,3 +1,5 @@
+.. _Glossary:
+
 Glossary
 ########