Merge pull request #4332 from YosysHQ/krys/help_docs

Add docs generation from cells help output

.github/workflows/prepare-docs.yml

@@ -64,6 +64,11 @@ jobs:
             docs/source/_images
             docs/source/code_examples
 
+      - name: Install doc prereqs
+        shell: bash
+        run: |
+          make docs/reqs
+
       - name: Test build docs
         shell: bash
         run: |

Makefile

@@ -981,8 +981,20 @@ endif
 
 # also others, but so long as it doesn't fail this is enough to know we tried
 docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS)
-	mkdir -p docs/source/cmd
-	./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
+	$(Q) mkdir -p docs/source/cmd
+	$(Q) mkdir -p temp/docs/source/cmd
+	$(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
+	$(Q) rsync -rc temp/docs/source/cmd docs/source
+	$(Q) rm -rf temp
+docs/source/cell/word_add.rst: $(TARGETS) $(EXTRA_TARGETS)
+	$(Q) mkdir -p docs/source/cell
+	$(Q) mkdir -p temp/docs/source/cell
+	$(Q) cd temp && ./../$(PROGRAM_PREFIX)yosys -p 'help -write-rst-cells-manual'
+	$(Q) rsync -rc temp/docs/source/cell docs/source
+	$(Q) rm -rf temp
+
+docs/source/generated/cells.json: docs/source/generated $(TARGETS) $(EXTRA_TARGETS)
+	$(Q) ./$(PROGRAM_PREFIX)yosys -p 'help -dump-cells-json $@'
 
 PHONY: docs/gen_examples docs/gen_images docs/guidelines docs/usage docs/reqs
 docs/gen_examples: $(TARGETS)
@@ -1025,7 +1037,7 @@ docs/reqs:
 	$(Q) $(MAKE) -C docs reqs
 
 .PHONY: docs/prep
-docs/prep: docs/source/cmd/abc.rst docs/gen_examples docs/gen_images docs/guidelines docs/usage
+docs/prep: docs/source/cmd/abc.rst docs/source/generated/cells.json docs/gen_examples docs/gen_images docs/guidelines docs/usage
 
 DOC_TARGET ?= html
 docs: docs/prep

docs/source/appendix/auxlibs.rst

@@ -29,30 +29,30 @@ 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 :cmd:ref:`sat` pass (see
+library is written by C. Wolf. It is used by the `sat` pass (see
 :doc:`/cmd/sat`).
 
 fst
 ---
 
 ``libfst`` files from `gtkwave`_ are included in ``libs/fst`` to support
 reading/writing signal traces from/to the GTKWave developed FST format.  This is
-primarily used in the :cmd:ref:`sim` command.
+primarily used in the `sim` command.
 
 .. _gtkwave: https://github.com/gtkwave/gtkwave
 
 json11
 ------
 
-For reading/writing designs from/to JSON, :cmd:ref:`read_json` and
-:cmd:ref:`write_json` should be used.  For everything else there is the `json11
+For reading/writing designs from/to JSON, `read_json` and
+`write_json` should be used.  For everything else there is the `json11
 library`_:
 
    json11 is a tiny JSON library for C++11, providing JSON parsing and
    serialization.
 
-This library is used for outputting machine-readable statistics (:cmd:ref:`stat`
-with ``-json`` flag), using the RPC frontend (:cmd:ref:`connect_rpc`), and the
+This library is used for outputting machine-readable statistics (`stat`
+with ``-json`` flag), using the RPC frontend (`connect_rpc`), and the
 yosys-witness ``yw`` format.
 
 .. _json11 library: https://github.com/dropbox/json11
@@ -61,7 +61,7 @@ MiniSAT
 -------
 
 The files in ``libs/minisat`` provide a high-performance SAT solver, used by the
-:cmd:ref:`sat` command.
+`sat` command.
 
 SHA1
 ----

docs/source/appendix/env_vars.rst

@@ -3,7 +3,7 @@ Yosys environment variables
 
 ``HOME``
    Yosys command history is stored in :file:`$HOME/.yosys_history`.  Graphics
-   (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this
+   (from `show` and `viz` commands) will output to this
    directory by default.  This environment variable is also used in some cases
    for resolving filenames with :file:`~`.
 

docs/source/yosys_internals/formats/rtlil_text.rst → docs/source/appendix/rtlil_text.rst

@@ -223,8 +223,8 @@ Cells
 Declares a cell, with zero or more attributes, with the given identifier and
 type in the enclosing module.
 
-Cells perform functions on input signals. See
-:doc:`/yosys_internals/formats/cell_library` for a detailed list of cell types.
+Cells perform functions on input signals. See :doc:`/cell_index` for a detailed
+list of cell types.
 
 .. code:: BNF
 

docs/source/cell/gate_comb_combined.rst

@@ -0,0 +1,53 @@
+.. role:: verilog(code)
+   :language: Verilog
+
+Combinatorial cells (combined)
+------------------------------
+
+These cells combine two or more combinatorial cells (simple) into a single cell.
+
+.. table:: Cell types for gate level combinatorial cells (combined)
+
+   ======================================= =============
+   Verilog                                 Cell Type
+   ======================================= =============
+   :verilog:`Y = A & ~B`                   `$_ANDNOT_`
+   :verilog:`Y = A | ~B`                   `$_ORNOT_`
+   :verilog:`Y = ~((A & B) | C)`           `$_AOI3_`
+   :verilog:`Y = ~((A | B) & C)`           `$_OAI3_`
+   :verilog:`Y = ~((A & B) | (C & D))`     `$_AOI4_`
+   :verilog:`Y = ~((A | B) & (C | D))`     `$_OAI4_`
+   :verilog:`Y = ~(S ? B : A)`             `$_NMUX_`
+   (see below)                             `$_MUX4_`
+   (see below)                             `$_MUX8_`
+   (see below)                             `$_MUX16_`
+   ======================================= =============
+
+The `$_MUX4_`, `$_MUX8_` and `$_MUX16_` cells are used to model wide muxes, and
+correspond to the following Verilog code:
+
+.. code-block:: verilog
+   :force:
+
+   // $_MUX4_
+   assign Y = T ? (S ? D : C) :
+                  (S ? B : A);
+   // $_MUX8_
+   assign Y = U ? T ? (S ? H : G) :
+                      (S ? F : E) :
+                  T ? (S ? D : C) :
+                      (S ? B : A);
+   // $_MUX16_
+   assign Y = V ? U ? T ? (S ? P : O) :
+                          (S ? N : M) :
+                      T ? (S ? L : K) :
+                          (S ? J : I) :
+                  U ? T ? (S ? H : G) :
+                          (S ? F : E) :
+                      T ? (S ? D : C) :
+                          (S ? B : A);
+
+.. autocellgroup:: comb_combined
+   :members:
+   :source:
+   :linenos:

docs/source/cell/gate_comb_simple.rst

@@ -0,0 +1,26 @@
+.. role:: verilog(code)
+   :language: Verilog
+
+Combinatorial cells (simple)
+----------------------------
+
+.. table:: Cell types for gate level combinatorial cells (simple)
+
+   ======================================= =============
+   Verilog                                 Cell Type
+   ======================================= =============
+   :verilog:`Y = A`                        `$_BUF_`
+   :verilog:`Y = ~A`                       `$_NOT_`
+   :verilog:`Y = A & B`                    `$_AND_`
+   :verilog:`Y = ~(A & B)`                 `$_NAND_`
+   :verilog:`Y = A | B`                    `$_OR_`
+   :verilog:`Y = ~(A | B)`                 `$_NOR_`
+   :verilog:`Y = A ^ B`                    `$_XOR_`
+   :verilog:`Y = ~(A ^ B)`                 `$_XNOR_`
+   :verilog:`Y = S ? B : A`                `$_MUX_`
+   ======================================= =============
+
+.. autocellgroup:: comb_simple
+   :members:
+   :source:
+   :linenos:

docs/source/cell/gate_other.rst

@@ -0,0 +1,8 @@
+Other gate-level cells
+----------------------
+
+.. autocellgroup:: gate_other
+   :caption: Other gate-level cells
+   :members:
+   :source:
+   :linenos: