TODOs

Blocking tasks are now capital TODO (compared to non-blocking todo).
Updated some of the todos.
Added note about which intel synth does which families.
Rename extended Yosys universe to Yosys family.
Added brief text to landing page, and also a note about the restructure and where to find old docs.
Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header).

Fixed pdf build, was previously breaking on trying to include the svg badges.

docs/source/appendix/auxlibs.rst

@@ -4,7 +4,7 @@ Auxiliary libraries
 The Yosys source distribution contains some auxiliary libraries that are
 compiled into Yosys and can be used in plugins.
 
-.. todo:: fill out the newer auxiliary libs
+.. TODO:: fill out the newer auxiliary libs
 
 BigInt
 ------

docs/source/appendix/auxprogs.rst

@@ -19,7 +19,7 @@ Yosys. See :doc:`/yosys_internals/extensions` for details.
 yosys-filterlib
 ---------------
 
-.. todo:: how does a filterlib rules-file work?  is this still supported?
+.. todo:: how does a filterlib rules-file work?
 
 The ``yosys-filterlib`` tool is a small utility that can be used to strip or
 extract information from a Liberty file.  This can be useful for removing

docs/source/getting_started/example_synth.rst

@@ -23,8 +23,9 @@ A simple counter
 .. role:: yoscrypt(code)
    :language: yoscrypt
 
-.. todo:: consider changing simple counter example for something with memory
-   using e.g. synth_ice40 to cover more of the synth flow
+.. TODO:: move current example synth as mapping to cell libraries
+
+   replace with a walk through of synth_ice40
 
 This section covers an `example project`_ available in
 ``docs/source/code_examples/intro/``.  The project contains a simple ASIC
@@ -77,7 +78,7 @@ stopping the following commands from trying to work on them.  By passing the
 that if the design includes any non-blackbox modules without an implementation
 it should return an error.
 
-.. todo:: more on why :cmd:ref:`hierarchy` is important
+.. TODO:: more on why :cmd:ref:`hierarchy` is important
 
 .. note::
 
@@ -147,7 +148,7 @@ Much better.  We can now see that the ``$dff`` and ``$mux`` cells have been
 replaced with a single ``$sdffe``, using the built-in enable and reset ports
 instead.
 
-.. todo:: a bit more on :cmd:ref:`opt` here
+.. TODO:: a bit more on :cmd:ref:`opt` here
 
 At this stage of a synthesis flow there are a few other commands we could run.
 First off is :cmd:ref:`flatten`.  If we had any modules within our ``counter``,
@@ -176,7 +177,7 @@ Such elements have to be inferred from patterns in the design and there are
 special passes for each.  Detection of these patterns can also be affected by
 optimizations and other transformations done previously.
 
-.. todo:: talk more about DSPs (and their associated commands)
+.. TODO:: talk more about DSPs (and their associated commands)
 
 Some of the commands we might use here are:
 
@@ -194,7 +195,7 @@ Some of the commands we might use here are:
 Logic gate mapping
 ~~~~~~~~~~~~~~~~~~
 
-.. todo:: example_synth mapping to gates
+.. TODO:: example_synth mapping to gates
 
 :yoscrypt:`techmap` - Map coarse-grain RTL cells (adders, etc.) to fine-grain
 logic gates (AND, OR, NOT, etc.).
@@ -217,7 +218,7 @@ cells used.
 Mapping to hardware
 ~~~~~~~~~~~~~~~~~~~
 
-.. todo:: example_synth mapping to hardware
+.. TODO:: example_synth mapping to hardware
 
 :ref:`cmos_lib`
 

docs/source/getting_started/index.rst

@@ -1,6 +1,8 @@
 Getting started with Yosys
 ==========================
 
+.. todo:: brief overview for the getting started index
+
 .. toctree::
    :maxdepth: 3
 

docs/source/getting_started/installation.rst

@@ -34,22 +34,24 @@ Targeted architectures
 
 The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
 
-- linux-x64 |linux-x64|
-   - Most personal Linux based computers
+.. only:: html
 
-- darwin-x64 |darwin-x64|
-   - macOS 10.14 or later with Intel CPU
+   - linux-x64 |linux-x64|
+      - Most personal Linux based computers
 
-- darwin-arm64 |darwin-arm64|
-   - macOS 11.00 or later with M1 CPU
+   - darwin-x64 |darwin-x64|
+      - macOS 10.14 or later with Intel CPU
 
-- windows-x64 |windows-x64|
-   - Targeted for Windows 10 and 11, but older 64-bit version of Windows 7, 8,
-     or 8.1 should work
+   - darwin-arm64 |darwin-arm64|
+      - macOS 11.00 or later with M1 CPU
 
-- linux-arm |linux-arm|
-- linux-arm64 |linux-arm64|
-- linux-riscv64 (untested) |linux-riscv64|
+   - windows-x64 |windows-x64|
+      - 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
@@ -141,7 +143,7 @@ executable name).
 Source tree and build system
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. todo:: check if source tree/build system details need updating
+.. TODO:: check if source tree/build system details need updating
 
 The Yosys source tree is organized into the following top-level
 directories:

docs/source/getting_started/scripting_intro.rst

@@ -1,7 +1,7 @@
 Scripting in Yosys
 ------------------
 
-.. todo:: check logical consistency
+.. TODO:: logical consistency, esp with example_synth
 
 Yosys reads and processes commands from synthesis scripts, command line
 arguments and an interactive command prompt. Yosys commands consist of a command

docs/source/index.rst

@@ -2,16 +2,30 @@
 Yosys Open SYnthesis Suite
 ================================================================================
 
-.. todo:: better landing page
-   
-   Consider adding something here that isn't just table of contents since this 
-   *is* the root page and is where the logo links to.
+Yosys is an open source framework for RTL synthesis.  To learn more about Yosys,
+see :doc:`/introduction`.  For a quick guide on how to get started using Yosys,
+check out :doc:`/getting_started/index`.  For the complete list of commands
+available, go to :ref:`commandindex`.
+
+.. note::
+
+   This documentation recently went through a major restructure.  If you're
+   looking for something from the previous version and can't find it here,
+   please `let us know`_.  Documentation from before the restructure can still
+   be found by switching to `version 0.36`_ or earlier.  Note that the previous
+   theme does not include a version switcher.
+
+.. _let us know: https://github.com/YosysHQ/yosys/issues/new/choose
+.. _version 0.36: https://yosyshq.readthedocs.io/projects/yosys/en/0.36/
 
 .. todo:: look into command ref improvements
 
    - Search bar with live drop down suggestions for matching on title /
      autocompleting commands
    - Scroll the left sidebar to the current location on page load
+   - Also the formatting/linking in pdf is broken
+
+.. todolist::
 
 .. only:: html
 
@@ -28,16 +42,3 @@ Yosys Open SYnthesis Suite
 	test_suites
 
 	appendix
-
-.. only:: html
-
-   Indices
-   -------
-
-   - :ref:`commandindex`
-   - :ref:`tagindex`
-
-TODOs
------
-
-.. todolist::

docs/source/introduction.rst

@@ -7,8 +7,8 @@ more general infrastructure for research on synthesis.
 
 Modern Yosys has full support for the synthesizable subset of Verilog-2005 and
 has been described as "the GCC of hardware synthesis."  Freely available and
-`open source`_, Yosys finds use across hobbyist and commercial applications as well
-as academic.
+`open source`_, Yosys finds use across hobbyist and commercial applications as
+well as academic.
 
 .. _open source: https://github.com/YosysHQ/yosys
 
@@ -71,8 +71,15 @@ Things you can't do
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
 
-The extended Yosys universe
----------------------------
+The Yosys family
+----------------
+
+As mentioned above, `YosysHQ`_ maintains not just Yosys but an entire family of
+tools built around it.
+
+.. _YosysHQ: https://github.com/YosysHQ
+
+.. TODO:: Yosys family descriptions
 
 In no particular order:
 

docs/source/test_suites.rst

@@ -9,8 +9,10 @@ Automatic testing
 The `Yosys Git repo`_ has automatic testing of builds and running of the
 included test suite on the following platforms:
 
-- Ubuntu 20.04 (Focal Fossa) |test-linux|
-- macOS 11 (Big Sur) |test-macos|
+.. only:: html
+
+   - Ubuntu 20.04 (Focal Fossa) |test-linux|
+   - macOS 11 (Big Sur) |test-macos|
 
 .. _Yosys Git repo: https://github.com/YosysHQ/yosys
 

docs/source/using_yosys/index.rst

@@ -1,6 +1,8 @@
 Using Yosys (advanced)
 ======================
 
+.. todo:: brief overview for the using Yosys index
+
 .. toctree:: 
 	:maxdepth: 2
 

docs/source/using_yosys/more_scripting/index.rst

@@ -1,6 +1,8 @@
 More scripting
 --------------
 
+.. todo:: brief overview for the more scripting index
+
 .. toctree::
    :maxdepth: 3
 

docs/source/using_yosys/more_scripting/interactive_investigation.rst

@@ -260,7 +260,7 @@ switch back). Now the `ls` command lists the objects within that module.
 :numref:`lscd` below demonstrates this using the ``example.v`` from
 `A simple circuit`_
 
-.. todo:: update yosys output with $ternary$example.v$3
+.. TODO:: update yosys output with $ternary$example.v$3
 
 .. code-block:: none
    :caption: Demonstration of :cmd:ref:`ls` and :cmd:ref:`cd` having run ``yosys example.v``

docs/source/using_yosys/more_scripting/selections.rst

@@ -263,7 +263,7 @@ diagram in :numref:`memdemo_00`.
    
    Complete circuit diagram for the design shown in :numref:`memdemo_src`
 
-.. todo:: :ref:`memdemo_01` and :ref:`memdemo_02` are the same, probably change
+.. TODO:: :ref:`memdemo_01` and :ref:`memdemo_02` are the same, probably change
           the example so they aren't.
 
 There's a lot going on there, but maybe we are only interested in the tree of

docs/source/using_yosys/synthesis/abc.rst

@@ -1,7 +1,7 @@
 The :cmd:ref:`abc` command
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. todo:: discuss abc (more stable) vs abc9 (newer, possibly better)
+.. TODO:: discuss abc, consider using https://github.com/Ravenslofty/yosys-cookbook/blob/master/misc/abc9.md
 
 The :cmd:ref:`abc` command provides an interface to ABC_, an open source tool
 for low-level logic synthesis.

docs/source/using_yosys/synthesis/index.rst

@@ -1,6 +1,8 @@
 Synthesis in detail
 -------------------
 
+.. todo:: brief overview for the synthesis index
+
 .. toctree::
    :maxdepth: 3
 

docs/source/using_yosys/synthesis/memory.rst

@@ -57,7 +57,7 @@ Example
 Memory mapping
 ^^^^^^^^^^^^^^
 
-.. todo:: :cmd:ref:`memory_libmap` description
+.. TODO:: :cmd:ref:`memory_libmap` description
 
 Usually it is preferred to use architecture-specific RAM resources for memory.
 For example:

docs/source/using_yosys/synthesis/opt.rst

@@ -66,8 +66,6 @@ In some cases this pass can also optimize cells with some constant inputs.
    1         :math:`b` :math:`b`
    ========= ========= ===========
 
-.. todo:: How to format table?
-
 :numref:`Table %s <tab:opt_expr_and>` shows the replacement rules used for
 optimizing an ``$_AND_`` gate. The first three rules implement the obvious const
 folding rules. Note that 'any' might include dynamic values calculated by other
@@ -131,7 +129,7 @@ is produced.
 The ``opt_rmdff`` pass
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. todo:: Update to ``opt_dff``
+.. TODO:: Update to ``opt_dff``
 
 This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and
 ``$adff`` cells) with a constant data input and replaces them with a constant

docs/source/using_yosys/synthesis/synth.rst

@@ -4,11 +4,10 @@ Synth commands
 Packaged ``synth_*`` commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. todo:: are all these synth commands supported?
-
 The following is a list of all synth commands included in Yosys for different
 platforms.  Each command runs a script of sub commands specific to the platform
-being targeted.
+being targeted.  Note that not all of these scripts are actively maintained and
+may not be up-to-date.
 
 - :doc:`/cmd/synth_achronix`
 - :doc:`/cmd/synth_anlogic`
@@ -21,8 +20,8 @@ being targeted.
 - :doc:`/cmd/synth_gowin`
 - :doc:`/cmd/synth_greenpak4`
 - :doc:`/cmd/synth_ice40`
-- :doc:`/cmd/synth_intel`
-- :doc:`/cmd/synth_intel_alm`
+- :doc:`/cmd/synth_intel` (MAX10, Cyclone IV)
+- :doc:`/cmd/synth_intel_alm` (Cyclone V, Arria V, Cyclone 10 GX)
 - :doc:`/cmd/synth_lattice`
 - :doc:`/cmd/synth_nexus`
 - :doc:`/cmd/synth_quicklogic`

docs/source/using_yosys/yosys_flows.rst

@@ -4,7 +4,7 @@ Flows, command types, and order
 Command order
 -------------
 
-.. todo:: check text is coherent
+.. TODO:: check text is coherent
 
 Intro to coarse-grain synthesis
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/yosys_internals/formats/rtlil_rep.rst

@@ -74,7 +74,7 @@ This has three advantages:
 -  First, it is impossible that an auto-generated identifier collides with an
    identifier that was provided by the user.
 
-.. todo:: ``opt_clean`` (or clean), also ``-purge``
+.. TODO:: ``opt_clean`` (or clean), also ``-purge``
 
 -  Second, the information about which identifiers were originally provided by
    the user is always available which can help guide some optimizations. For