Docs: Add :cmd:title: directive

Calling :cmd:title:`<cmd>` will generate a cross reference to `<cmd>`, but unlike :cmd:ref: which displays a literal block and puts the title (short_help) in the hovertext (the title field of an a-ref), :cmd:title: will display "<cmd> - <short_help>" as plain text.
Thus replacing the previous use case of referring to :doc:`cmd/<cmd>`.
Also refactor util py scripts to have more descriptive names.

docs/source/conf.py

@@ -82,13 +82,13 @@
 
 # custom cmd-ref parsing/linking
 sys.path += [os.path.dirname(__file__) + "/../"]
-extensions.append('util.cmdref')
+extensions.append('util.custom_directives')
 
 # use autodocs
 extensions.append('sphinx.ext.autodoc')
-extensions.append('util.cellref')
+extensions.append('util.cell_documenter')
 cells_json = Path(__file__).parent / 'generated' / 'cells.json'
-extensions.append('util.newcmdref')
+extensions.append('util.cmd_documenter')
 cmds_json = Path(__file__).parent / 'generated' / 'cmds.json'
 
 from sphinx.application import Sphinx

docs/source/getting_started/example_synth.rst

@@ -143,8 +143,8 @@ 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: :cmd:ref:`proc`. `proc`
-is a macro command like `synth_ice40`.  Rather than modifying the design
+To handle these, let us now introduce the next command: :cmd:title:`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
 multiplexers and registers.  Let's see what happens when we run it.  For now, we
@@ -188,7 +188,7 @@ opt_expr <adv_opt_expr>`.
 
 .. note::
 
-   :cmd:ref:`clean` can also be called with two semicolons after any command,
+   :cmd:title:`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:
 
-- :cmd:ref:`design`, and
-- :cmd:ref:`read_verilog`.
+- :cmd:title:`design`, and
+- :cmd:title:`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 :cmd:ref:`show`.  Note that the `show` command only works
+you can do so with :cmd:title:`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`.
@@ -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:
-:cmd:ref:`fsm`.  Both `opt` and `fsm` are macro commands which are explored in
+:cmd:title:`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.
 
@@ -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 :cmd:ref:`wreduce`.  If we run this we get the following:
+First up is :cmd:title:`wreduce`.  If we run this we get the following:
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -432,15 +432,15 @@ the schematic and see the output of that cell has now changed.
 
    ``rdata`` output after `wreduce`
 
-The next two (new) commands are :cmd:ref:`peepopt` and :cmd:ref:`share`.
+The next two (new) commands are :cmd:title:`peepopt` and :cmd:title:`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
 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
-:cmd:ref:`memory_dff`.
+:cmd:title:`memory_dff`.
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -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 :cmd:ref:`memory`.  `memory` is another
+The other new command in this part is :cmd:title:`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,
@@ -793,9 +793,9 @@ tidy up:
 
 The new commands here are:
 
-- :cmd:ref:`autoname`,
-- :cmd:ref:`stat`, and
-- :cmd:ref:`blackbox`.
+- :cmd:title:`autoname`,
+- :cmd:title:`stat`, and
+- :cmd:title:`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
@@ -847,4 +847,4 @@ is beyond the scope of this documentation.
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
 
-.. seealso:: :cmd:ref:`synth_ice40`
+.. seealso:: :cmd:title:`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
-:cmd:ref:`select`.
+:cmd:title:`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
-:cmd:ref:`show`.
+:cmd:title:`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,10 +323,10 @@ 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.
-- :cmd:ref:`show`.
-- :cmd:ref:`dump`.
-- :cmd:ref:`add` and :cmd:ref:`delete` can be used to modify and reorganize a
-  design dynamically.
+- :cmd:title:`show`.
+- :cmd:title:`dump`.
+- :cmd:title:`add` and :cmd:title:`delete` can be used to modify and reorganize
+  a design dynamically.
 
 The code used is included in the Yosys code base under
 |code_examples/scrambler|_.
@@ -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 :cmd:ref:`eval`:
+Analyzing the resulting circuit with :cmd:title:`eval`:
 
 .. todo:: replace inline code
 

docs/source/using_yosys/more_scripting/load_design.rst

@@ -31,10 +31,10 @@ keyword: Frontends
 
 .. note::
 
-   The Verific frontend for Yosys, which provides the :cmd:ref:`verific`
-   command, requires Yosys to be built with Verific.  For full functionality,
-   custom modifications to the Verific source code from YosysHQ are required,
-   but limited useability can be achieved with some stock Verific builds.  Check
+   The Verific frontend for Yosys, which provides the `verific` command,
+   requires Yosys to be built with Verific.  For full functionality, custom
+   modifications to the Verific source code from YosysHQ are required, but
+   limited useability can be achieved with some stock Verific builds.  Check
    :doc:`/yosys_internals/extending_yosys/build_verific` for more.
 
 Others:

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 :cmd:ref:`select`.
+A complete list of pattern expressions can be found in :cmd:title:`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 :cmd:ref:`select` for the full list.
+See :cmd:title:`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 :cmd:ref:`select` for full documentation of these expressions.
+Again, see :cmd:title:`select` for full documentation of these expressions.
 
 Incremental selection
 ^^^^^^^^^^^^^^^^^^^^^

docs/source/using_yosys/synthesis/synth.rst

@@ -15,7 +15,7 @@ General synthesis
 ~~~~~~~~~~~~~~~~~
 
 In addition to the above hardware-specific synth commands, there is also
-:cmd:ref:`prep`.  This command is limited to coarse-grain synthesis, without
+:cmd:title:`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.
 

docs/util/cmdref.py → docs/util/custom_directives.py

@@ -7,9 +7,8 @@
 import warnings
 
 from docutils import nodes
-from docutils.nodes import Node, Element
+from docutils.nodes import Node, Element, Text
 from docutils.parsers.rst import directives
-from docutils.parsers.rst.roles import GenericRole
 from docutils.parsers.rst.states import Inliner
 from sphinx.application import Sphinx
 from sphinx.domains import Domain, Index
@@ -598,12 +597,17 @@ def generate(self, docnames=None):
 
         return (ret, True)
 
+class TitleRefRole(XRefRole):
+    """XRefRole used which has the cmd title as the displayed text."""
+    pass
+
 class CommandDomain(Domain):
     name = 'cmd'
     label = 'Yosys commands'
 
     roles = {
-        'ref': XRefRole()
+        'ref': XRefRole(),
+        'title': TitleRefRole(),
     }
 
     directives = {
@@ -635,7 +639,7 @@ def get_objects(self):
 
     def resolve_xref(self, env, fromdocname, builder, typ,
                      target, node, contnode):
-        
+
         match = [(docname, anchor, name)
                  for name, sig, typ, docname, anchor, prio
                  in self.get_objects() if sig == target]
@@ -645,9 +649,17 @@ def resolve_xref(self, env, fromdocname, builder, typ,
             targ = match[0][1]
             qual_name = match[0][2]
             title = self.data['obj2title'].get(qual_name, targ)
-
-            return make_refnode(builder,fromdocname,todocname,
-                                targ, contnode, title)
+
+            if typ == 'title':
+                # caller wants the title in the content of the node
+                cmd = contnode.astext()
+                contnode = Text(f'{cmd} - {title}')
+                return make_refnode(builder, fromdocname, todocname,
+                                    targ, contnode)
+            else:
+                # cmd title as hover text
+                return make_refnode(builder, fromdocname, todocname,
+                                    targ, contnode, title)
         else:
             print(f"Missing ref for {target} in {fromdocname} ")
             return None