Docs: tidying

- Use `:file:` role for file names, as well as `:makevar:` and `:program:`.
- Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets.
- Add link to ABC.
- More (and better) links to code examples.  Formatted `:file:` text with link
  to source on github.
- Includes a few extra todos (mostly picking up inline code blocks and a couple
  intro reminders).
- Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags.
- Reflowing some paragraphs for spacing/width.

docs/source/getting_started/example_synth.rst

@@ -26,7 +26,7 @@ First, let's quickly look at the design we'll be synthesizing:
 .. literalinclude:: /code_examples/fifo/fifo.v
    :language: Verilog
    :linenos:
-   :caption: ``fifo.v``
+   :caption: :file:`fifo.v`
    :name: fifo-v
 
 .. todo:: fifo.v description
@@ -36,7 +36,7 @@ Loading the design
 
 Let's load the design into Yosys.  From the command line, we can call ``yosys
 fifo.v``.  This will open an interactive Yosys shell session and immediately
-parse the code from ``fifo.v`` and convert it into an Abstract Syntax Tree
+parse the code from :ref:`fifo-v` and convert it into an Abstract Syntax Tree
 (AST).  If you are interested in how this happens, there is more information in
 the document, :doc:`/yosys_internals/flow/verilog_frontend`.  For now, suffice
 it to say that we do this to simplify further processing of the design.  You
@@ -214,7 +214,7 @@ could restart our shell session, but instead let's use two new commands:
    :language: doscon
    :start-at: design -reset
    :end-before: yosys> proc
-   :caption: reloading ``fifo.v`` and running :yoscrypt:`hierarchy -check -top fifo`
+   :caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo`
 
 Notice how this time we didn't see any of those `$abstract` modules?  That's
 because when we ran ``yosys fifo.v``, the first command Yosys called was
@@ -234,7 +234,7 @@ design.  If we know that our design won't run into this issue, we can skip the
    The number before a command's output increments with each command run.  Don't
    worry if your numbers don't match ours!  The output you are seeing comes from
    the same script that was used to generate the images in this document,
-   included in the source as ``fifo.ys``. There are extra commands being run
+   included in the source as :file:`fifo.ys`. There are extra commands being run
    which you don't see, but feel free to try them yourself, or play around with
    different commands.  You can always start over with a clean slate by calling
    ``exit`` or hitting ``ctrl+c`` (i.e. SIGINT) and re-launching the Yosys
@@ -305,8 +305,8 @@ optimizations between modules which would otherwise be missed.  Let's run
 
 The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from
 earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`.  We can
-also see that the ``addr`` output has been renamed to ``fifo_reader.addr`` and
-merged with the ``raddr`` wire feeding into the ``$memrd`` cell.  This wire
+also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr`
+and merged with the ``raddr`` wire feeding into the ``$memrd`` cell.  This wire
 merging happened during the call to :cmd:ref:`clean` which we can see in the
 :ref:`flat_clean`.  Note that in an interactive terminal the outputs of
 :cmd:ref:`flatten` and :cmd:ref:`clean` will be combined into a single
@@ -803,11 +803,11 @@ The iCE40 synthesis flow has the following output modes available:
 - :doc:`/cmd/write_json`.
 
 As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
-our synthesized ``fifo`` design will be output as ``fifo.json``.  We can then
-read the design back into Yosys with :cmd:ref:`read_json`, but make sure you use
-:yoscrypt:`design -reset` or open a new interactive terminal first.  The JSON
-output we get can also be loaded into `nextpnr`_ to do place and route; but that
-is beyond the scope of this documentation.
+our synthesized ``fifo`` design will be output as :file:`fifo.json`.  We can
+then read the design back into Yosys with :cmd:ref:`read_json`, but make sure
+you use :yoscrypt:`design -reset` or open a new interactive terminal first.  The
+JSON output we get can also be loaded into `nextpnr`_ to do place and route; but
+that is beyond the scope of this documentation.
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
 

docs/source/getting_started/installation.rst

@@ -49,9 +49,7 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
       - Targeted for Windows 10 and 11, but older 64-bit version of Windows 7,
         8, or 8.1 should work
 
-   - linux-arm |linux-arm|
    - linux-arm64 |linux-arm64|
-   - linux-riscv64 (untested) |linux-riscv64|
 
 .. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build
 .. _nightly builds: https://github.com/YosysHQ/oss-cad-suite-build/releases/latest
@@ -60,9 +58,7 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
 .. |darwin-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-x64.yml/badge.svg
 .. |darwin-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-arm64.yml/badge.svg
 .. |windows-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/windows-x64.yml/badge.svg
-.. |linux-arm| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm.yml/badge.svg
 .. |linux-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm64.yml/badge.svg
-.. |linux-riscv64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-riscv64.yml/badge.svg
 
 Building from source
 ~~~~~~~~~~~~~~~~~~~~
@@ -133,8 +129,10 @@ Then, simply run ``make`` in this directory.
    make
    sudo make install
 
-Note that this also downloads, builds, and installs ABC (using yosys-abc as the
-executable name).
+Note that this also downloads, builds, and installs `ABC`_ (using
+:program:`yosys-abc` as the executable name).
+
+.. _ABC: https://github.com/berkeley-abc/abc
 
 .. seealso:: 
 
@@ -167,11 +165,12 @@ directories:
 ``kernel/``
    This directory contains all the core functionality of Yosys. This includes
    the functions and definitions for working with the RTLIL data structures
-   (``rtlil.{h|cc}``), the ``main()`` function (``driver.cc``), the internal
-   framework for generating log messages (``log.{h|cc}``), the internal
-   framework for registering and calling passes (``register.{h|cc}``), some core
-   commands that are not really passes (``select.cc``, ``show.cc``, …) and a
-   couple of other small utility libraries.
+   (:file:`rtlil.{h|cc}`), the ``main()`` function (:file:`driver.cc`), the
+   internal framework for generating log messages (:file:`log.{h|cc}`), the
+   internal framework for registering and calling passes
+   (:file:`register.{h|cc}`), some core commands that are not really passes
+   (:file:`select.cc`, :file:`show.cc`, …) and a couple of other small utility
+   libraries.
 
 ``libs/``
    Libraries packaged with Yosys builds are contained in this folder.  See
@@ -182,7 +181,7 @@ directories:
 
 ``passes/``
    This directory contains a subdirectory for each pass or group of passes. For
-   example as of this writing the directory ``passes/hierarchy/`` contains the
+   example as of this writing the directory :file:`passes/hierarchy/` contains the
    code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and
    :cmd:ref:`uniquify`.
 
@@ -194,15 +193,16 @@ directories:
    This directory contains the suite of unit tests and regression tests used by
    Yosys.  See :doc:`/test_suites`.
 
-The top-level Makefile includes ``frontends/*/Makefile.inc``,
-``passes/*/Makefile.inc`` and ``backends/*/Makefile.inc``. So when extending
-Yosys it is enough to create a new directory in ``frontends/``, ``passes/`` or
-``backends/`` with your sources and a ``Makefile.inc``. The Yosys kernel
-automatically detects all commands linked with Yosys. So it is not needed to add
-additional commands to a central list of commands.
+The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`,
+:file:`passes/{*}/Makefile.inc` and :file:`backends/{*}/Makefile.inc`. So when
+extending Yosys it is enough to create a new directory in :file:`frontends/`,
+:file:`passes/` or :file:`backends/` with your sources and a
+:file:`Makefile.inc`. The Yosys kernel automatically detects all commands linked
+with Yosys. So it is not needed to add additional commands to a central list of
+commands.
 
 Good starting points for reading example source code to learn how to write
-passes are ``passes/opt/opt_dff.cc`` and ``passes/opt/opt_merge.cc``.
+passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
 
 See the top-level README file for a quick Getting Started guide and build
 instructions. The Yosys build is based solely on Makefiles.

docs/source/getting_started/scripting_intro.rst

@@ -5,13 +5,13 @@ On the previous page we went through a synthesis script, running each command in
 the interactive Yosys shell.  On this page, we will be introducing the script
 file format and how you can make your own synthesis scripts.
 
-Yosys script files typically use the ``.ys`` extension and contain a set of
+Yosys script files typically use the :file:`.ys` extension and contain a set of
 commands for Yosys to run sequentially.  These commands are the same ones we
 were using on the previous page like :cmd:ref:`read_verilog` and
 :cmd:ref:`hierarchy`.  As with the interactive shell, each command consists of
 the command name, and an optional whitespace separated list of arguments.
-Commands are terminated with the newline character, or by a semicolon (;).
-Empty lines, and lines starting with the hash sign (#), are ignored.
+Commands are terminated with the newline character, or by a semicolon (;). Empty
+lines, and lines starting with the hash sign (#), are ignored.
 
 The synthesis starter script
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -21,7 +21,7 @@ The synthesis starter script
 
 All of the images and console output used in
 :doc:`/getting_started/example_synth` were generated by Yosys, using Yosys
-script files found in ``docs/source/code_examples/fifo``. If you haven't
+script files found in :file:`docs/source/code_examples/fifo`. If you haven't
 already, let's take a look at some of those script files now.
 
 .. literalinclude:: /code_examples/fifo/fifo.ys
@@ -29,7 +29,7 @@ already, let's take a look at some of those script files now.
    :lineno-match:
    :start-at: echo on
    :end-before: design -reset
-   :caption: A section of ``fifo.ys``, generating the images used for :ref:`addr_gen_example`
+   :caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example`
    :name: fifo-ys
 
 The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable
@@ -121,9 +121,9 @@ what the different symbols represent, see :ref:`interactive_show` and the
 .. _GraphViz: http://www.graphviz.org/
 .. _xdot: https://github.com/jrfonseca/xdot.py
 
-This is the first :yoscrypt:`show` command we called in ``fifo.ys``, :ref:`as we
-saw above <fifo-ys>`.  If we look at the log output for this image we see the
-following:
+This is the first :yoscrypt:`show` command we called in :file:`fifo.ys`,
+:ref:`as we saw above <fifo-ys>`.  If we look at the log output for this image
+we see the following:
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -131,14 +131,14 @@ following:
    :end-before: yosys> show
 
 Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output
-a ``.dot`` file rather than opening it for display.  The :yoscrypt:`-prefix
-addr_gen_show` option indicates we want the file to be called `addr_gen_show.*`.
-Remember, we do this in ``fifo.ys`` because we need to store the image for
-displaying in the documentation you're reading.  But if you just want to display
-the images locally you can skip these two options.  The ``-format`` option
-internally calls the ``dot`` command line program from GraphViz to convert to
-formats other than ``.dot``.  Check `GraphViz output docs`_ for more on
-available formats.
+a :file:`.dot` file rather than opening it for display.  The :yoscrypt:`-prefix
+addr_gen_show` option indicates we want the file to be called
+:file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we
+need to store the image for displaying in the documentation you're reading.  But
+if you just want to display the images locally you can skip these two options.
+The ``-format`` option internally calls the ``dot`` command line program from
+GraphViz to convert to formats other than :file:`.dot`.  Check `GraphViz output
+docs`_ for more on available formats.
 
 .. _GraphViz output docs: https://graphviz.org/docs/outputs/