From 76379d94deab3635a620288519f5aed7d5ff6d3e Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 25 Jan 2025 11:30:08 +1300
Subject: [PATCH] docs: Initial documentation for generated help

Very briefly on command help
Mostly focused on v1 and v2 of the cell help, but still largely bullet points
---
 .../extending_yosys/contributing.rst          | 160 ++++++++++++++++++
 1 file changed, 160 insertions(+)

diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst
index e06de61b165..8c76dabb7d4 100644
--- a/docs/source/yosys_internals/extending_yosys/contributing.rst
+++ b/docs/source/yosys_internals/extending_yosys/contributing.rst
@@ -34,3 +34,163 @@ for implicit type casts, always use ``GetSize(foobar)`` instead of
 ``foobar.size()``. (``GetSize()`` is defined in :file:`kernel/yosys.h`)
 
 Use range-based for loops whenever applicable.
+
+Generated help messages and documentation
+-----------------------------------------
+
+Command help
+~~~~~~~~~~~~
+
+- `help` without arguments
+
+  - lists all commands with their ``Pass::short_help``
+
+- ``help <command>``
+
+  - calls ``Pass::help()`` for ``<command>``
+
+.. note::
+
+   A more expressive way to generate formatted help messages is `in
+   development`_.
+
+.. _in development: https://github.com/YosysHQ/yosys/pull/4860
+
+Cell help
+~~~~~~~~~
+
+- :file:`techlibs/common/simcells.v` and :file:`techlibs/common/simlib.v`
+- parsed by :file:`techlibs/common/cellhelp.py`
+- comments preceding cell type converted to a ``SimHelper`` struct, defined in
+  :file:`kernel/register.cc`
+- ``#include``d in :file:`kernel/register.cc`, creating a map of cell types to
+  their ``SimHelper`` struct.
+
+- ``help -cells``
+
+  - lists all cells with their input/output ports
+
+- ``help <celltype>``
+
+  - prints help message for ``<celltype>``
+  - constructed from ``SimHelper`` content depending on version
+
+- ``help <celltype>+``
+
+  - prints verilog code for ``<celltype>``
+
+v1 (default)
+^^^^^^^^^^^^
+
+- Legacy format
+- Expects formatting as follows:
+
+.. code-block:: verilog
+
+   //-
+   //-    $<celltype> (<ports>)
+   //* group <cellgroup>
+   //-
+   //- <cell description>
+   //-
+   module \$<celltype> (<ports>);
+   // ...
+   endmodule
+
+- ``//* group`` line is generally after the cell signature, but can appear
+  anywhere in the comment block
+
+  - determines where the cell is included in sphinx
+  - check :file:`docs/source/cell` for current groups
+  - a missing group will raise an error
+  - assigning an unused group will result in the cell not being included in the
+    sphinx docs
+
+- the port signature line (``//-    $<celltype> (<ports>)``) must start with (at
+  least) 4 spaces (not tabs)
+
+  - the empty lines (``//-``) before/after the signature are required
+
+- cell description can be multiple lines, but each line must start with ``//-``
+  and a space
+
+  - description should have a trailing empty line
+  - line breaks are preserved in `help` calls but will be rendered as text in
+    sphinx docs, with empty lines being required between paragraphs
+
+- cells in :file:`techlibs/common/simcells.v` can have optional truth table at
+  the end of the cell description which is rendered in sphinx docs as a literal
+  code block
+- e.g. `$_NOT_`:
+
+.. code-block:: verilog
+
+   //-
+   //-     $_NOT_ (A, Y)
+   //* group comb_simple
+   //-
+   //- An inverter gate.
+   //-
+   //- Truth table:    A | Y
+   //-                ---+---
+   //-                 0 | 1
+   //-                 1 | 0
+   //-
+
+v2 (more expressive)
+^^^^^^^^^^^^^^^^^^^^
+
+- each field of the ``SimHelper`` struct can be assigned with:
+
+.. code-block:: verilog
+
+   //* <name> <value>
+
+- ``ver`` must be explicitly set as ``2``
+- optional fields ``title`` and ``tags``
+
+  - title used for better displaying of cell
+  - tags is a space-separated list of :doc:`/cell/properties`
+
+- the port signature is automatically generated from the ``module`` definition
+- cell description is the same as v1
+- 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.
+   //-
+
+- code blocks can be included as following:
+
+.. code-block:: verilog
+
+   //- text
+   //- ::
+   //-
+   //-    monospaced text
+   //-
+   //-        indentation and line length will be preserved, giving a scroll bar if necessary for the browser window
+   //-
+   //- more text
+
+- the empty line after the ``::`` and before the text continues are required
+- the ``::`` line will be ignored in the `help` call while sphinx docs will
+  treat everything that follows as a literal block until the next unindented
+  line:
+
+   text
+   ::
+
+      monospaced text
+
+         indentation and line length will be preserved, giving a scroll bar if necessary for the browser window
+
+   more text