Docs: Fix warnings

Changes a bunch of :doc:`/cmd/*` to :cmd:ref:`*` with the intention of changing it later to something that replicates the previous effect of displaying the commands `short_help`.

docs/source/appendix/auxlibs.rst

@@ -29,8 +29,7 @@ ezSAT
 
 The files in ``libs/ezsat`` provide a library for simplifying generating CNF
 formulas for SAT solvers. It also contains bindings of MiniSAT. The ezSAT
-library is written by C. Wolf. It is used by the `sat` pass (see
+library is written by C. Wolf. It is used by the `sat` pass.
-:doc:`/cmd/sat`).
 
 fst
 ---
@@ -78,4 +77,4 @@ SubCircuit
 The files in ``libs/subcircuit`` provide a library for solving the subcircuit
 isomorphism problem. It is written by C. Wolf and based on the Ullmann Subgraph
 Isomorphism Algorithm :cite:p:`UllmannSubgraphIsomorphism`. It is used by the
-extract pass (see :doc:`../cmd/extract`).
+`extract` pass.

docs/source/cmd/index_techlibs.rst

@@ -1,5 +1,9 @@
 techlibs
 ------------------
 
+.. TODO:: disambiguate `synth_intel` and `synth_intel_alm`
+
+   (MAX10, Cyclone IV) and (Cyclone V, Arria V, Cyclone 10 GX) respectively
+
 .. autocmdgroup:: techlibs
    :members:

docs/source/code_examples/macro_commands/prep.ys

@@ -0,0 +1,23 @@
+#start:The following commands are executed by this synthesis command:
+#end:$
+begin:
+    hierarchy -check [-top <top> | -auto-top]
+
+coarse:
+    proc [-ifx]
+    flatten    (if -flatten)
+    future
+    opt_expr -keepdc
+    opt_clean
+    check
+    opt -noff -keepdc
+    wreduce -keepdc [-memx]
+    memory_dff    (if -rdff)
+    memory_memx    (if -memx)
+    opt_clean
+    memory_collect
+    opt -noff -keepdc -fast
+
+check:
+    stat
+    check

docs/source/getting_started/example_synth.rst

@@ -70,7 +70,7 @@ At the bottom of the `help` output for
 `synth_ice40` is the complete list of commands called by this script.
 Let's start with the section labeled ``begin``:
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: begin:
    :end-before: flatten:
@@ -143,7 +143,7 @@ line refers to the line numbers of the start/end of the corresponding ``always
 @`` block.  In the case of an ``initial`` block, we instead see the ``PROC``
 referring to line 0.
 
-To handle these, let us now introduce the next command: :doc:`/cmd/proc`. `proc`
+To handle these, let us now introduce the next command: :cmd:ref:`proc`. `proc`
 is a macro command like `synth_ice40`.  Rather than modifying the design
 directly, it instead calls a series of other commands.  In the case of `proc`,
 these sub-commands work to convert the behavioral logic of processes into
@@ -188,7 +188,7 @@ opt_expr <adv_opt_expr>`.
 
 .. note::
 
-   :doc:`/cmd/clean` can also be called with two semicolons after any command,
+   :cmd:ref:`clean` can also be called with two semicolons after any command,
    for example we could have called :yoscrypt:`opt_expr;;` instead of
    :yoscrypt:`opt_expr; clean`.  You may notice some scripts will end each line
    with ``;;``.  It is beneficial to run `clean` before inspecting intermediate
@@ -215,8 +215,8 @@ Note that if we tried to run this command now then we would get an error.  This
 is because we already removed all of the modules other than ``addr_gen``.  We
 could restart our shell session, but instead let's use two new commands:
 
-- :doc:`/cmd/design`, and
+- :cmd:ref:`design`, and
-- :doc:`/cmd/read_verilog`.
+- :cmd:ref:`read_verilog`.
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -251,7 +251,7 @@ our design won't run into this issue, we can skip the ``-defer``.
 We can also run `proc` now to finish off the full :ref:`synth_begin`. Because
 the design schematic is quite large, we will be showing just the data path for
 the ``rdata`` output.  If you would like to see the entire design for yourself,
-you can do so with :doc:`/cmd/show`.  Note that the `show` command only works
+you can do so with :cmd:ref:`show`.  Note that the `show` command only works
 with a single module, so you may need to call it with :yoscrypt:`show fifo`.
 :ref:`show_intro` section in :doc:`/getting_started/scripting_intro` has more on
 how to use `show`.
@@ -283,7 +283,7 @@ Flattening
 At this stage of a synthesis flow there are a few other commands we could run.
 In `synth_ice40` we get these:
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: flatten:
    :end-before: coarse:
@@ -355,7 +355,7 @@ Part 1
 
 In the iCE40 flow, we start with the following commands:
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: coarse:
    :end-before: wreduce
@@ -371,7 +371,7 @@ wasting time on something we know is impossible.
 Next up is :yoscrypt:`opt -nodffe -nosdff` performing a set of simple
 optimizations on the design.  This command also ensures that only a specific
 subset of FF types are included, in preparation for the next command:
-:doc:`/cmd/fsm`.  Both `opt` and `fsm` are macro commands which are explored in
+:cmd:ref:`fsm`.  Both `opt` and `fsm` are macro commands which are explored in
 more detail in :doc:`/using_yosys/synthesis/opt` and
 :doc:`/using_yosys/synthesis/fsm` respectively.
 
@@ -403,7 +403,7 @@ Part 2
 
 The next group of commands performs a series of optimizations:
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-at: wreduce
    :end-before: t:$mul
@@ -411,7 +411,7 @@ The next group of commands performs a series of optimizations:
    :caption: ``coarse`` section (part 2)
    :name: synth_coarse2
 
-First up is :doc:`/cmd/wreduce`.  If we run this we get the following:
+First up is :cmd:ref:`wreduce`.  If we run this we get the following:
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -432,7 +432,7 @@ the schematic and see the output of that cell has now changed.
 
    ``rdata`` output after `wreduce`
 
-The next two (new) commands are :doc:`/cmd/peepopt` and :doc:`/cmd/share`.
+The next two (new) commands are :cmd:ref:`peepopt` and :cmd:ref:`share`.
 Neither of these affect our design, and they're explored in more detail in
 :doc:`/using_yosys/synthesis/opt`, so let's skip over them.  :yoscrypt:`techmap
 -map +/cmp2lut.v -D LUT_WIDTH=4` optimizes certain comparison operators by
@@ -440,7 +440,7 @@ converting them to LUTs instead.  The usage of `techmap` is explored more in
 :doc:`/using_yosys/synthesis/techmap_synth`.
 
 Our next command to run is
-:doc:`/cmd/memory_dff`.
+:cmd:ref:`memory_dff`.
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -475,7 +475,7 @@ will only be performed if called with the ``-dsp`` flag: :yoscrypt:`synth_ice40
 -dsp`.  While our example has nothing that could be mapped to DSPs we can still
 take a quick look at the commands here and describe what they do.
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-at: t:$mul
    :end-before: alumacc
@@ -514,7 +514,7 @@ Part 4
 
 That brings us to the fourth and final part for the iCE40 synthesis flow:
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-at: alumacc
    :end-before: map_ram:
@@ -543,7 +543,7 @@ Once these cells have been inserted, the call to `opt` can combine cells which
 are now identical but may have been missed due to e.g. the difference between
 `$add` and `$sub`.
 
-The other new command in this part is :doc:`/cmd/memory`.  `memory` is another
+The other new command in this part is :cmd:ref:`memory`.  `memory` is another
 macro command which we examine in more detail in
 :doc:`/using_yosys/synthesis/memory`.  For this document, let us focus just on
 the step most relevant to our example: `memory_collect`. Up until this point,
@@ -594,7 +594,7 @@ Memory blocks
 Mapping to hard memory blocks uses a combination of `memory_libmap` and
 `techmap`.
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: map_ram:
    :end-before: map_ffram:
@@ -636,7 +636,7 @@ into flip flops (the ``logic fallback``) with `memory_map`.
 .. |techlibs/ice40/brams_map.v| replace:: :file:`techlibs/ice40/brams_map.v`
 .. _techlibs/ice40/brams_map.v: https://github.com/YosysHQ/yosys/tree/main/techlibs/ice40/brams_map.v
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: map_ffram:
    :end-before: map_gates:
@@ -671,7 +671,7 @@ an explosion in cells as multi-bit `$mux` and `$adffe` are replaced with
 single-bit `$_MUX_` and `$_DFFE_PP0P_` cells, while the `$alu` is replaced with
 primitive `$_OR_` and `$_NOT_` gates and a `$lut` cell.
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: map_gates:
    :end-before: map_ffs:
@@ -700,7 +700,7 @@ mapped to hardware into gate-level primitives.  This includes optimizing
 `$_MUX_` cells where one of the inputs is a constant ``1'0``, replacing it
 instead with an `$_AND_` cell.
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: map_ffs:
    :end-before: map_luts:
@@ -725,7 +725,7 @@ LUTs
 `abc`. For more on what these do, and what the difference between these two
 commands are, refer to :doc:`/using_yosys/synthesis/abc`.
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: map_luts:
    :end-before: map_cells:
@@ -742,7 +742,7 @@ commands are, refer to :doc:`/using_yosys/synthesis/abc`.
 Finally we use `techmap` to map the generic `$lut` cells to iCE40 ``SB_LUT4``
 cells.
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: map_cells:
    :end-before: check:
@@ -784,19 +784,18 @@ Final steps
 The next section of the iCE40 synth flow performs some sanity checking and final
 tidy up:
 
-.. literalinclude:: /cmd/synth_ice40.rst
+.. literalinclude:: /code_examples/macro_commands/synth_ice40.ys
    :language: yoscrypt
    :start-after: check:
-   :end-before: blif:
    :dedent:
    :name: check
    :caption: ``check`` section
 
 The new commands here are:
 
-- :doc:`/cmd/autoname`,
+- :cmd:ref:`autoname`,
-- :doc:`/cmd/stat`, and
+- :cmd:ref:`stat`, and
-- :doc:`/cmd/blackbox`.
+- :cmd:ref:`blackbox`.
 
 The output from `stat` is useful for checking resource utilization; providing a
 list of cells used in the design and the number of each, as well as the number
@@ -835,9 +834,9 @@ Synthesis output
 
 The iCE40 synthesis flow has the following output modes available:
 
-- :doc:`/cmd/write_blif`,
+- `write_blif`,
-- :doc:`/cmd/write_edif`, and
+- `write_edif`, and
-- :doc:`/cmd/write_json`.
+- `write_json`.
 
 As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
 our synthesized ``fifo`` design will be output as :file:`fifo.json`.  We can
@@ -848,4 +847,4 @@ is beyond the scope of this documentation.
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
 
-.. seealso:: :doc:`/cmd/synth_ice40`
+.. seealso:: :cmd:ref:`synth_ice40`

docs/source/getting_started/scripting_intro.rst

@@ -122,7 +122,7 @@ module.
 
 Detailed documentation of the select framework can be found under
 :doc:`/using_yosys/more_scripting/selections` or in the command reference at
-:doc:`/cmd/select`.
+:cmd:ref:`select`.
 
 .. _show_intro:
 
@@ -219,7 +219,7 @@ those used in options, must be a single expression instead.
 .. _GraphViz color docs: https://graphviz.org/doc/info/colors
 
 For all of the options available to `show`, check the command reference at
-:doc:`/cmd/show`.
+:cmd:ref:`show`.
 
 .. seealso:: :ref:`interactive_show` on the
    :doc:`/using_yosys/more_scripting/interactive_investigation` page.

docs/source/using_yosys/more_scripting/interactive_investigation.rst

@@ -323,9 +323,9 @@ tools).
   design into an equivalent design that is easier to analyse.
 - Commands such as `eval` and `sat` can be used to investigate the behavior of
   the circuit.
-- :doc:`/cmd/show`.
+- :cmd:ref:`show`.
-- :doc:`/cmd/dump`.
+- :cmd:ref:`dump`.
-- :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a
+- :cmd:ref:`add` and :cmd:ref:`delete` can be used to modify and reorganize a
   design dynamically.
   
 The code used is included in the Yosys code base under
@@ -358,7 +358,7 @@ reorganizing a module in Yosys and checking the resulting circuit.
 .. figure:: /_images/code_examples/scrambler/scrambler_p02.*
     :class: width-helper invert-helper
 
-Analyzing the resulting circuit with :doc:`/cmd/eval`:
+Analyzing the resulting circuit with :cmd:ref:`eval`:
 
 .. todo:: replace inline code
 

docs/source/using_yosys/more_scripting/load_design.rst

@@ -1,9 +1,11 @@
 Loading a design
 ~~~~~~~~~~~~~~~~
 
+.. TODO:: fill out this page better
+
 keyword: Frontends
 
-- :doc:`/cmd/read_verilog`
+- :doc:`/cmd/index_frontends`
 
 .. todo:: include ``read_verilog <<EOF``, also other methods of loading designs
 
@@ -37,12 +39,6 @@ keyword: Frontends
 
 Others:
 
-- :doc:`/cmd/read`
 - `GHDL plugin`_ for VHDL
-- :doc:`/cmd/read_rtlil` (direct textual representation of Yosys internal state)
-- :doc:`/cmd/read_aiger`
-- :doc:`/cmd/read_blif`
-- :doc:`/cmd/read_json`
-- :doc:`/cmd/read_liberty`
 
 .. _GHDL plugin: https://github.com/ghdl/ghdl-yosys-plugin

docs/source/using_yosys/more_scripting/selections.rst

@@ -93,7 +93,7 @@ Special patterns can be used to select by object property or type. For example:
   A:blabla`
 - select all `$add` cells from the module foo: :yoscrypt:`select foo/t:$add`
 
-A complete list of pattern expressions can be found in :doc:`/cmd/select`.
+A complete list of pattern expressions can be found in :cmd:ref:`select`.
 
 Operations on selections
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -141,7 +141,7 @@ Some of the special ``%``-codes:
 - ``%i``: intersection of top two elements on stack -- pop 2, push 1
 - ``%n``: inverse of top element on stack -- pop 1, push 1
 
-See :doc:`/cmd/select` for the full list.
+See :cmd:ref:`select` for the full list.
 
 Expanding selections
 ^^^^^^^^^^^^^^^^^^^^
@@ -354,7 +354,7 @@ boolean operations such as intersection (``%i``) and difference (``%d``) are
 powerful tools for extracting the relevant portions of the circuit under
 investigation.
 
-Again, see :doc:`/cmd/select` for full documentation of these expressions.
+Again, see :cmd:ref:`select` for full documentation of these expressions.
 
 Incremental selection
 ^^^^^^^^^^^^^^^^^^^^^

docs/source/using_yosys/synthesis/fsm.rst

@@ -10,7 +10,7 @@ other commands:
    :start-after: #end:
    :caption: Passes called by `fsm`
 
-See also :doc:`/cmd/fsm`.
+See also :doc:`/cmd/index_passes_fsm`.
 
 The algorithms used for FSM detection and extraction are influenced by a more
 general reported technique :cite:p:`fsmextract`.

docs/source/using_yosys/synthesis/memory.rst

@@ -26,7 +26,7 @@ Some quick notes:
    decoder logic and registers.
 
 For more information about `memory`, such as disabling certain sub commands, see
-:doc:`/cmd/memory`.
+:doc:`/cmd/index_passes_memory`.
 
 Example
 -------

docs/source/using_yosys/synthesis/opt.rst

@@ -11,8 +11,8 @@ The `opt` macro command
 
 The Yosys pass `opt` runs a number of simple optimizations. This includes
 removing unused signals and cells and const folding. It is recommended to run
-this pass after each major step in the synthesis script.  As listed in
+this pass after each major step in the synthesis script.  This macro command
-:doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
+calls the following ``opt_*`` commands:
 
 .. literalinclude:: /code_examples/macro_commands/opt.ys
    :language: yoscrypt
@@ -226,7 +226,5 @@ Other optimizations
 
 .. todo:: more on the other optimizations
 
-- :doc:`/cmd/wreduce`
+- Check :doc:`/cmd/index_passes_opt` for more.
-- :doc:`/cmd/peepopt`
-- :doc:`/cmd/share`
 - `abc` and `abc9`, see also: :doc:`abc`.

docs/source/using_yosys/synthesis/proc.rst

@@ -17,7 +17,7 @@ commands in a sensible order:
 
 After all the ``proc_*`` commands, `opt_expr` is called. This can be disabled by
 calling :yoscrypt:`proc -noopt`.  For more information about `proc`, such as
-disabling certain sub commands, see :doc:`/cmd/proc`.
+disabling certain sub commands, see :doc:`/cmd/index_passes_proc`.
 
 Many commands can not operate on modules with "processess" in them. Usually a
 call to `proc` is the first command in the actual synthesis procedure after

docs/source/using_yosys/synthesis/synth.rst

@@ -6,44 +6,23 @@ Synth commands
 Packaged ``synth_*`` commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following is a list of all synth commands included in Yosys for different
+A list of all synth commands included in Yosys for different platforms can be
-platforms.  Each command runs a script of sub commands specific to the platform
+found under :doc:`/cmd/index_techlibs`.  Each command runs a script of sub
-being targeted.  Note that not all of these scripts are actively maintained and
+commands specific to the platform being targeted.  Note that not all of these
-may not be up-to-date.
+scripts are actively maintained and may not be up-to-date.
-
-- :doc:`/cmd/synth_achronix`
-- :doc:`/cmd/synth_anlogic`
-- :doc:`/cmd/synth_coolrunner2`
-- :doc:`/cmd/synth_easic`
-- :doc:`/cmd/synth_ecp5`
-- :doc:`/cmd/synth_efinix`
-- :doc:`/cmd/synth_fabulous`
-- :doc:`/cmd/synth_gatemate`
-- :doc:`/cmd/synth_gowin`
-- :doc:`/cmd/synth_greenpak4`
-- :doc:`/cmd/synth_ice40`
-- :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`
-- :doc:`/cmd/synth_sf2`
-- :doc:`/cmd/synth_xilinx`
 
 General synthesis
 ~~~~~~~~~~~~~~~~~
 
 In addition to the above hardware-specific synth commands, there is also
-:doc:`/cmd/prep`.  This command is limited to coarse-grain synthesis, without
+:cmd:ref:`prep`.  This command is limited to coarse-grain synthesis, without
 getting into any architecture-specific mappings or optimizations.  Among other
 things, this is useful for design verification.
 
 The following commands are executed by the `prep` command:
 
-.. literalinclude:: /cmd/prep.rst
+.. literalinclude:: /code_examples/macro_commands/prep.ys
    :start-at: begin:
-   :end-before: .. only:: latex
-   :dedent:
 
 :doc:`/getting_started/example_synth` covers most of these commands and what
 they do.

docs/source/using_yosys/synthesis/techmap_synth.rst

@@ -33,9 +33,9 @@ reader may find this map file as :file:`techlibs/common/techmap.v` in the Yosys
 source tree.
 
 Additional features have been added to techmap to allow for conditional mapping
-of cells (see :doc:`/cmd/techmap`). This can for example be useful if the target
+of cells (see :doc:`/cmd/index_passes_techmap`). This can for example be useful
-architecture supports hardware multipliers for certain bit-widths but not for
+if the target architecture supports hardware multipliers for certain bit-widths
-others.
+but not for others.
 
 A usual synthesis flow would first use the techmap pass to directly map some RTL
 cells to coarse-grain cells provided by the target architecture (if any) and

docs/util/newcmdref.py

@@ -305,7 +305,10 @@ class YosysCmdDocumenter(YosysCmdGroupDocumenter):
         return False
 
     def get_sourcename(self) -> str:
-        return self.object.source_file
+        try:
+            return self.object.source_file
+        except AttributeError:
+            return super().get_sourcename()
     
     def format_name(self) -> str:
         return self.object.name