From 657b0bd92b6090b757086f203ec32967e2806c95 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 18 Nov 2025 12:20:33 +1300 Subject: [PATCH] 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 | 22 +++++-- .../extending_yosys/documenting.rst | 57 +++++++++---------- 2 files changed, 45 insertions(+), 34 deletions(-) diff --git a/Makefile b/Makefile index dd7a8c022..8f61a1a8d 100644 --- a/Makefile +++ b/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 diff --git a/docs/source/yosys_internals/extending_yosys/documenting.rst b/docs/source/yosys_internals/extending_yosys/documenting.rst index 08218b1de..c64e57f97 100644 --- a/docs/source/yosys_internals/extending_yosys/documenting.rst +++ b/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. -If a word would cause the 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. +spaces). Any ``codeblock`` nodes are rendered as-is at the current indentation, +with no further formatting applied. -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 +.. TODO:: are codeblocks actually rendered as-is? They definitely should be + +``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 - - //* ver 2 - //* title Case inequality - //* group binary - //* tags x-aware - //- This corresponds to the Verilog '!==' operator. - //- - //- Refer to `$eqx` for more details. - //- +.. literalinclude:: /generated/simlib.nex.v + :language: verilog - 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