docs/f4pga: update

Signed-off-by: Unai Martinez-Corral <[email protected]>

docs/f4pga/Deprecated.rst

@@ -5,7 +5,8 @@ Understanding the (deprecated) flow
 
 .. IMPORTANT::
   This section describes the usage of the now deprecated ``symbiflow_*`` entrypoints/wrappers.
-  It is provided for backwards compatibility, so that users of the *old* flow can keep using it.
+  It is provided for :gh:`backwards compatibility <chipsalliance/fpga-tool-perf/pull/390#issuecomment-1023487178>`, so
+  that users of the *old* flow can keep using it.
   However, it is recommended for new users to use the approach explained in :ref:`pyF4PGA`.
 
 This section provides valuable information on how each of the commands used to compile and build

docs/f4pga/Status.rst

@@ -1,52 +1,51 @@
 Package capability status
 #########################
 
-* Architecture support:
+* Supports incremental builds.
 
-    * Xilinx XC7 (**available** in main branch)
+* Supports multiple configurations for a single project.
 
-        * Synthesis tool: yosys
+* Provides a Python interface to ``F4PGA``, however there's no official API at the moment.
 
-        * PnR tool: VPR
+Architectures and flows
+=======================
 
-        * bitstream generation: yes (xcfasm)
+Xilinx XC7
+----------
 
-        * used in f4pga-examples: :gh:`yes <chipsalliance/f4pga-examples/blob/main/xc7/counter_test/flow.json>`
+* Synthesis tool: yosys
+* PnR tool: VPR
+* bitstream generation: yes (xcfasm)
+* used in f4pga-examples: :gh:`yes <chipsalliance/f4pga-examples/blob/main/xc7/counter_test/flow.json>`
 
-    * Quicklogic EOS-S3 (yosys+VPR flow) (**WIP**, see :ghsharp:`577`)
+Quicklogic EOS-S3
+-----------------
 
-        * Synthesis tool: yosys
+* Synthesis tool: yosys
+* PnR tool: VPR
+* bitstream generation: yes (qlfasm)
+* analysis: ?
+* used in f4pga-examples: no
 
-        * PnR tool: VPR
+Lattice ICE40
+-------------
 
-        * bitstream generation: yes (qlfasm)
+.. IMPORTANT::
+   **WIP** :ghsharp:`585`
 
-        * analysis: ?
+* Synthesis tool: yosys
+* PnR tool: nextpnr
+* bitstream generation: yes (icepack)
+* used in f4pga-examples: no
 
-        * used in f4pga-examples: no
+Quicklogic k4n8
+---------------
 
-    * Lattice ICE40 (yosys+nextpnr flow) (**WIP**, see :ghsharp:`585`)
+* Synthesis tool: yosys
+* PnR tool: VPR
+* bitstream generation: yes (qlf_fasm)
+* used in f4pga-examples: no
 
-        * Synthesis tool: yosys
-
-        * PnR tool: nextpnr
-
-        * bitstream generation: yes (icepack)
-
-        * used in f4pga-examples: no
-
-    * Quicklogic k4n8 (Unverified, not officially supported. Might work after some tinkering.)
-
-        * Synthesis tool: yosys
-
-        * PnR tool: VPR
-
-        * bitstream generation: yes (qlf_fasm)
-
-        * used in f4pga-examples: no
-
-* Incremental builds support
-
-* Support for multiple configurations for a single project
-
-* Can be used as a python interface to _F4PGA_, however there's no official _API_ at the moment.
+.. NOTE::
+  Unverified, not officially supported.
+  Might work after some tinkering.

docs/f4pga/index.rst

@@ -9,40 +9,25 @@ The scope of Python F4PGA is threefold:
 
 * Provide a fine-grained *pythonic* interface to the tools and utilities available as either command-line interfaces
   (CLIs) or application proggraming interfaces (APIs) (either web or through shared libraries).
-* Provide a CLI entrypoint covering the whole flows for end-users to produce bitstreams from HDL and/or software sources.
+
+* Provide a unified CLI front-end covering the whole flows for end-users to produce bitstreams from HDL and/or software sources.
+  It's meant as a future replacement of the deprecated ``symbiflow_*`` shell scripts.
+
 * Provide a CLI entrypoint for developers contributing to bitstream documentation and testing (continuous integration).
 
 .. ATTENTION::
   This is work-in-progress to adapt and organize the existing shell/bash based plumbing from multiple F4PGA repositories.
   Therefore, it's still a *pre-alpha* and the codebase, commands and flows are subject to change.
   It is strongly suggested not to rely on Python F4PGA until this note is updated/removed.
 
-This is the current in-development FPGA-oriented build system that's provided with f4pga.
-
-This package aims to provide a unified front-end for executing *verilog-to-bitstream* and
-other flows for various FPGA platforms. It's meant as a future replacement of
-``symbiflow_*`` shell scripts.
-
-It contains *EDA* tool wrappers that provide meta-data about the tools, utilities
-related to tracking files and inspection of data used within the flows, scripts used by
-tools within flows, a dependency resolution algorithm and flow templates for various devices.
+``f4pga`` contains *EDA* tool wrappers that provide meta-data about the tools, utilities related to tracking files and
+inspection of data used within the flows, scripts used by tools within flows, a dependency resolution algorithm and flow
+templates for various devices.
 
 The basic usage requires creation of a ``flow.json`` file describing the FPGA-oriented project.
-You can take
-:gh:`one from the f4pga-examples repository <chipsalliance/f4pga-examples/blob/main/xc7/counter_test/flow.json>`
-as a reference. Alternatively there's a way to configure a flow with command-line parameters only.
-
-Once you have your flow created, run ``f4pga build -f flow.json`` to build a default target.
-
-To learn more about the package and its usage, visit :doc:`Usage`.
+See, for instance, example :gh:`xc7/counter_test/flow.json ➚ <chipsalliance/f4pga-examples/blob/main/xc7/counter_test/flow.json>`.
+Alternatively the flow can be configured through CLI arguments only.
 
-References
-==========
+With a given flow configuration, run ``f4pga build -f flow.json`` builds the default target.
 
-* :gh:`chipsalliance/fpga-tool-perf#390@issuecomment-1023487178 <chipsalliance/fpga-tool-perf/pull/390#issuecomment-1023487178>`
-* :ghsharp:`2225`
-* :ghsharp:`2371`
-* :ghsharp:`2455`
-* `F4PGA GSoC 2022 project ideas: Generalization of wrapper scripts for installed F4PGA toolchain and making them OS agnostic <https://github.com/f4pga/ideas/blob/master/gsoc-2022-ideas.md#generalization-of-wrapper-scripts-for-installed-f4pga-toolchain-and-making-them-OS-agnostic>`__
-* :gh:`FuseSoc <olofk/fusesoc>` | :gh:`Edalize <olofk/edalize>`
-* `Electronic Design Automation Abstraction (EDA²) <https://edaa-org.github.io/>`__
+See :doc:`Usage` to learn more about ``f4pga``.

docs/references.rst

@@ -6,3 +6,11 @@ References
 .. bibliography::
   :notcited:
   :labelprefix: R
+
+f4pga
+=====
+
+* :ghsharp:`530`
+* `F4PGA GSoC 2022 project ideas: Generalization of wrapper scripts for installed F4PGA toolchain and making them OS agnostic <https://github.com/f4pga/ideas/blob/master/gsoc-2022-ideas.md#generalization-of-wrapper-scripts-for-installed-f4pga-toolchain-and-making-them-OS-agnostic>`__
+* :gh:`FuseSoc <olofk/fusesoc>` | :gh:`Edalize <olofk/edalize>`
+* `Electronic Design Automation Abstraction (EDA²) <https://edaa-org.github.io/>`__