documenting.rst: literalinclude cell doc examples

Add a sed command to the (top level) makefile for extract comment block for the specified cell.  Works with both simlib.v and simcells.v (by abusing `%` pattern matching slightly to disambiguate which to search).

Makefile

@@ -1082,7 +1082,7 @@ docs/source/generated/functional/rosette.diff: backends/functional/smtlib.cc bac
 	$(Q) mkdir -p $(@D)
 	$(Q) diff -U 20 $^ > $@ || exit 0
 
-PHONY: docs/gen/functional_ir
+.PHONY: docs/gen/functional_ir
 docs/gen/functional_ir: docs/source/generated/functional/smtlib.cc docs/source/generated/functional/rosette.diff
 
 docs/source/generated/%.log: docs/source/generated $(TARGETS) $(EXTRA_TARGETS)
@@ -1091,10 +1091,24 @@ docs/source/generated/%.log: docs/source/generated $(TARGETS) $(EXTRA_TARGETS)
 docs/source/generated/chformal.cc: passes/cmds/chformal.cc docs/source/generated
 	$(Q) cp $< $@
 
-PHONY: docs/gen/chformal
+.PHONY: docs/gen/chformal
 docs/gen/chformal: docs/source/generated/chformal.log docs/source/generated/chformal.cc
 
-PHONY: docs/gen docs/usage docs/reqs
+# e.g. simlib.nex.v -> extract $nex from simlib.v
+# sed command adds all non-empty lines to the hold space
+#  when an empty line is reached, the hold space is moved to the pattern space
+#  if it includes the desired module, print it
+#  this gives us the raw comment block immediately before the cell
+docs/source/generated/%.v: $(addprefix techlibs/common/,simlib.v simcells.v)
+	$(Q) mkdir -p $(@D)
+	$(Q) sed --posix -n -e '/./{H;d} ; x' \
+		-e "/module .\$$$(lastword $(subst ., ,$*))/p" \
+		techlibs/common/$(basename $*).v >> $@
+
+.PHONY: docs/gen/raw_cells
+docs/gen/raw_cells: $(addprefix docs/source/generated/,simlib.nex.v  simcells._NOT_.v)
+
+.PHONY: docs/gen docs/usage docs/reqs
 docs/gen: $(TARGETS)
 	$(Q) $(MAKE) -C docs gen
 
@@ -1129,7 +1143,7 @@ docs/reqs:
 	$(Q) $(MAKE) -C docs reqs
 
 .PHONY: docs/prep
-docs/prep: docs/source/generated/cells.json docs/source/generated/cmds.json docs/gen docs/usage docs/gen/functional_ir docs/gen/chformal
+docs/prep: docs/source/generated/cells.json docs/source/generated/cmds.json docs/gen docs/usage docs/gen/functional_ir docs/gen/chformal docs/gen/raw_cells
 
 DOC_TARGET ?= html
 docs: docs/prep

docs/source/yosys_internals/extending_yosys/documenting.rst

@@ -239,13 +239,17 @@ Rendering rich help text as plain text is done by traversing over all the
 ``ContentListing`` nodes and printing the body text.  ``usage`` nodes are
 preceded by an empty line and indented one level (4 spaces).  ``option`` nodes
 are also indented one level, while their children are indented an extra level (8
-spaces).  Each section of body text is broken into words separated by spaces.
+spaces).  Any ``codeblock`` nodes are rendered as-is at the current indentation,
-If a word would cause the line to exceed 80 characters (controlled by
+with no further formatting applied.
-``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`), then the word will instead be
-placed on a new line, with the same level of indentation.
 
-Special handling is included for words that begin and end with a backtick
+.. TODO:: are codeblocks actually rendered as-is?  They definitely should be
-(`````) so that these are stripped when printing to the command line.  Compare
+
+``paragraph`` nodes are broken into words separated by spaces, and each word is
+printed.  If a word would cause the current line to exceed 80 characters
+(controlled by ``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`), then the word
+will instead be placed on a new line with the same level of indentation. Special
+handling is included for words that begin and end with a backtick (`````) so
+that these are stripped when printing to the command line.  Compare
 :ref:`chformal_help` below with the :ref:`chformal autocmd` above.  The content
 is still the same, but for the command line it uses a fixed width.
 
@@ -330,19 +334,11 @@ v1 (default)
   code block
 - e.g. `$_NOT_`:
 
-.. code-block:: verilog
+.. literalinclude:: /generated/simcells._NOT_.v
+   :language: verilog
+   :start-at: //-
+   :end-at: module \$_NOT_
 
-   //-
-   //-     $_NOT_ (A, Y)
-   //* group comb_simple
-   //-
-   //- An inverter gate.
-   //-
-   //- Truth table:    A | Y
-   //-                ---+---
-   //-                 0 | 1
-   //-                 1 | 0
-   //-
 
 v2 (more expressive)
 ~~~~~~~~~~~~~~~~~~~~
@@ -364,16 +360,8 @@ v2 (more expressive)
 - can link to commands or passes using backticks (`````)
 - e.g. `$nex`:
 
-.. code-block:: verilog
+.. literalinclude:: /generated/simlib.nex.v
-
+   :language: verilog
-   //* ver 2
-   //* title Case inequality
-   //* group binary
-   //* tags x-aware
-   //- This corresponds to the Verilog '!==' operator.
-   //-
-   //- Refer to `$eqx` for more details.
-   //-
 
 - code blocks can be included as following:
 
@@ -490,9 +478,18 @@ auto detection will break and revert to unformatted code (e.g.
 Cells JSON
 ~~~~~~~~~~
 
-- effectively (if not literally) the ``SimHelper`` struct formatted as JSON
+- effectively the ``SimHelper`` struct formatted as JSON (drops ``ver``, copies
+  tags to ``properties``)
+- plus additional fields from the ``CellType``
 
-.. todo:: get an example here (`$nex`\ ?)
+  + inputs, outputs, property flags
+
+.. literalinclude:: /generated/cells.json
+   :language: json
+   :start-at: "$nex": {
+   :end-at: },
+   :caption: `$nex` in generated :file:`cells.json`
+   :name: nex_json
 
 
 Cells and commands in Sphinx