From 2da76274916b1a5dec09b13f535812559e01b3d9 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Fri, 14 Nov 2025 14:21:59 +1300 Subject: [PATCH] docs: Move help guides to documenting.rst --- docs/source/cmd/index_internal.rst | 147 -------- .../extending_yosys/contributing.rst | 160 --------- .../extending_yosys/documenting.rst | 314 ++++++++++++++++++ .../yosys_internals/extending_yosys/index.rst | 1 + 4 files changed, 315 insertions(+), 307 deletions(-) create mode 100644 docs/source/yosys_internals/extending_yosys/documenting.rst diff --git a/docs/source/cmd/index_internal.rst b/docs/source/cmd/index_internal.rst index ab9c13aba..d485be705 100644 --- a/docs/source/cmd/index_internal.rst +++ b/docs/source/cmd/index_internal.rst @@ -3,150 +3,3 @@ Internal commands for developers .. autocmdgroup:: internal :members: - -Writing command help --------------------- - -- use `chformal` as an example -- generated help content below - -.. _chformal autocmd: - -.. autocmd:: chformal - :noindex: - -The ``formatted_help()`` method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- ``PrettyHelp::get_current()`` -- ``PrettyHelp::set_group()`` - - + used with ``.. autocmdgroup:: `` - + can assign group and return false - + if no group is set, will try to use ``source_location`` and assign group - from path to source file - -- return value - - + true means help content added to current ``PrettyHelp`` - + false to use ``Pass::help()`` - -- adding content - - + help content is a list of ``ContentListing`` nodes, each one having a type, - body, and its own list of children ``ContentListing``\ s - + ``PrettyHelp::get_root()`` returns the root ``ContentListing`` (``type="root"``) - + ``ContentListing::{usage, option, codeblock, paragraph}`` each add a - ``ContentListing`` to the current node, with type the same as the method - - * the first argument is the body of the new node - * ``usage`` shows how to call the command (i.e. its "signature") - * ``paragraph`` content is formatted as a paragraph of text with line breaks - added automatically - * ``codeblock`` content is displayed verbatim, use line breaks as desired; - takes an optional ``language`` argument for assigning the language in RST - output for code syntax highlighting (use ``yoscrypt`` for yosys script - syntax highlighting) - * ``option`` lists a single option for the command, usually starting with a - dash (``-``); takes an optional second argument which adds a paragraph - node as a means of description - - + ``ContentListing::open_usage`` creates and returns a new usage node, can be - used to e.g. add text/options specific to a given usage of the command - + ``ContentListing::open_option`` creates and returns a new option node, can - be used to e.g. add multiple paragraphs to an option's description - + paragraphs are treated as raw RST, allowing for inline formatting and - references as if it were written in the RST file itself - -.. literalinclude:: /generated/chformal.cc - :language: c++ - :start-at: bool formatted_help() - :end-before: void execute - :caption: ``ChformalPass::formatted_help()`` from :file:`passes/cmds/chformal.cc` - -Dumping command help to json -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `help -dump-cmds-json cmds.json` - - + generates a ``ContentListing`` for each command registered in Yosys - + tries to parse unformatted ``Pass::help()`` output if - ``Pass::formatted_help()`` is unimplemented or returns false - - * if a line starts with four spaces followed by the name of the command then - a space, it is parsed as a signature (usage node) - * if a line is indented and starts with a dash (``-``), it is parsed as an - option - * anything else is parsed as a codeblock and added to either the root node - or the current option depending on the indentation - - + dictionary of command name to ``ContentListing`` - - * uses ``ContentListing::to_json()`` recursively for each node in root - * root node used for source location of class definition - * includes flags set during pass constructor (e.g. ``experimental_flag`` set - by ``Pass::experimental()``) - * also title (``short_help`` argument in ``Pass::Pass``), group, and class - name - - + dictionary of group name to list of commands in that group - -- used by sphinx autodoc to generate help content - -.. literalinclude:: /generated/cmds.json - :language: json - :start-at: "chformal": { - :end-before: "chparam": { - :caption: `chformal` in generated :file:`cmds.json` - -.. note:: Synthesis command scripts are special cased - - If the final block of help output starts with the string `"The following - commands are executed by this synthesis command:\n"`, then the rest of the - code block is formatted as ``yoscrypt`` (e.g. `synth_ice40`). The caveat - here is that if the ``script()`` calls ``run()`` on any commands *prior* to - the first ``check_label`` then the auto detection will break and revert to - unformatted code (e.g. `synth_fabulous`). - -Command line rendering -~~~~~~~~~~~~~~~~~~~~~~ - -- if ``Pass::formatted_help()`` returns true, will call - ``PrettyHelp::log_help()`` - - + traverse over the children of the root node and render as plain text - + effectively the reverse of converting unformatted ``Pass::help()`` text - + lines are broken at 80 characters while maintaining indentation (controlled - by ``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`) - + each line is broken into words separated by spaces, if a given word starts - and ends with backticks they will be stripped - -- if it returns false it will call ``Pass::help()`` which should call ``log()`` - directly to print and format help text - - + if ``Pass::help()`` is not overridden then a default message about missing - help will be displayed - -.. literalinclude:: /generated/chformal.log - :lines: 2- - -RST generated from autocmd -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- below is the raw RST output from ``autocmd`` (``YosysCmdDocumenter`` class in - :file:`docs/util/cmd_documenter.py`) for `chformal` command -- heading will be rendered as a subheading of the most recent heading (see - `chformal autocmd`_ above rendered under `Writing command help`_) -- ``.. cmd:def:: `` line is indexed for cross references with ``:cmd:ref:`` - directive (`chformal autocmd`_ above uses ``:noindex:`` option so that - `chformal` still links to the correct location) - - + ``:title:`` option controls text that appears when hovering over the - `chformal` link - -- commands with warning flags (experimental or internal) add a ``.. warning`` - block before any of the help content -- if a command has no ``source_location`` the ``.. note`` at the bottom will - instead link to :doc:`/cmd/index_other` - -.. autocmd_rst:: chformal diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 65f29e592..70170fc48 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -176,163 +176,3 @@ Additional details + if the design is too big for a comment, consider turning it into a `Gist`_ .. _Gist: https://gist.github.com/ - -Generated help messages and documentation ------------------------------------------ - -Command help -~~~~~~~~~~~~ - -- `help` without arguments - - - lists all commands with their ``Pass::short_help`` - -- ``help `` - - - calls ``Pass::help()`` for ```` - -.. 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 `` - - - prints help message for ```` - - constructed from ``SimHelper`` content depending on version - -- ``help +`` - - - prints verilog code for ```` - -v1 (default) -^^^^^^^^^^^^ - -- Legacy format -- Expects formatting as follows: - -.. code-block:: verilog - - //- - //- $ () - //* group - //- - //- - //- - module \$ (); - // ... - 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 (``//- $ ()``) 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 - - //* - -- ``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 diff --git a/docs/source/yosys_internals/extending_yosys/documenting.rst b/docs/source/yosys_internals/extending_yosys/documenting.rst new file mode 100644 index 000000000..aee2cf80c --- /dev/null +++ b/docs/source/yosys_internals/extending_yosys/documenting.rst @@ -0,0 +1,314 @@ +Generated help messages and documentation +========================================= + +- (virtually) all Yosys commands and built-in cell types have help text +- see `help` (or call ``yosys -h help``) +- this help text is also used to generate the :doc:`/cmd_ref` and + :doc:`/cell_index` documentation, available online via `ReadtheDocs`_ + +.. _ReadtheDocs: https://about.readthedocs.com/ + +Command help +------------ + +- `help` without arguments + + - lists all commands with their ``Pass::short_help`` + +- ``help `` + + - provides command specific help content + - as an example, the help content for `chformal` is shown below + +.. _chformal autocmd: + +.. autocmd:: chformal + :noindex: + +The ``Pass::help()`` method +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- call ``log()`` directly to print and format help text +- arbitrary formatting is possible, though some recommendations for consistency + and correct parsing during RST generation + + + see `Dumping command help to json`_ for details + +The ``Pass::formatted_help()`` method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``PrettyHelp::get_current()`` +- ``PrettyHelp::set_group()`` + + + used with ``.. autocmdgroup:: `` + + can assign group and return false + + if no group is set, will try to use ``source_location`` and assign group + from path to source file + +- return value + + + true means help content added to current ``PrettyHelp`` + + false to use ``Pass::help()`` + +- adding content + + + help content is a list of ``ContentListing`` nodes, each one having a type, + body, and its own list of children ``ContentListing``\ s + + ``PrettyHelp::get_root()`` returns the root ``ContentListing`` (``type="root"``) + + ``ContentListing::{usage, option, codeblock, paragraph}`` each add a + ``ContentListing`` to the current node, with type the same as the method + + * the first argument is the body of the new node + * ``usage`` shows how to call the command (i.e. its "signature") + * ``paragraph`` content is formatted as a paragraph of text with line breaks + added automatically + * ``codeblock`` content is displayed verbatim, use line breaks as desired; + takes an optional ``language`` argument for assigning the language in RST + output for code syntax highlighting (use ``yoscrypt`` for yosys script + syntax highlighting) + * ``option`` lists a single option for the command, usually starting with a + dash (``-``); takes an optional second argument which adds a paragraph + node as a means of description + + + ``ContentListing::open_usage`` creates and returns a new usage node, can be + used to e.g. add text/options specific to a given usage of the command + + ``ContentListing::open_option`` creates and returns a new option node, can + be used to e.g. add multiple paragraphs to an option's description + + paragraphs are treated as raw RST, allowing for inline formatting and + references as if it were written in the RST file itself + +.. literalinclude:: /generated/chformal.cc + :language: c++ + :start-at: bool formatted_help() + :end-before: void execute + :caption: ``ChformalPass::formatted_help()`` from :file:`passes/cmds/chformal.cc` + + +Dumping command help to json +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `help -dump-cmds-json cmds.json` + + + generates a ``ContentListing`` for each command registered in Yosys + + tries to parse unformatted ``Pass::help()`` output if + ``Pass::formatted_help()`` is unimplemented or returns false + + * if a line starts with four spaces followed by the name of the command then + a space, it is parsed as a signature (usage node) + * if a line is indented and starts with a dash (``-``), it is parsed as an + option + * anything else is parsed as a codeblock and added to either the root node + or the current option depending on the indentation + + + dictionary of command name to ``ContentListing`` + + * uses ``ContentListing::to_json()`` recursively for each node in root + * root node used for source location of class definition + * includes flags set during pass constructor (e.g. ``experimental_flag`` set + by ``Pass::experimental()``) + * also title (``short_help`` argument in ``Pass::Pass``), group, and class + name + + + dictionary of group name to list of commands in that group + +- used by sphinx autodoc to generate help content + +.. literalinclude:: /generated/cmds.json + :language: json + :start-at: "chformal": { + :end-before: "chparam": { + :caption: `chformal` in generated :file:`cmds.json` + +.. note:: Synthesis command scripts are special cased + + If the final block of help output starts with the string `"The following + commands are executed by this synthesis command:\n"`, then the rest of the + code block is formatted as ``yoscrypt`` (e.g. `synth_ice40`). The caveat + here is that if the ``script()`` calls ``run()`` on any commands *prior* to + the first ``check_label`` then the auto detection will break and revert to + unformatted code (e.g. `synth_fabulous`). + + +Command line rendering +~~~~~~~~~~~~~~~~~~~~~~ + +- if ``Pass::formatted_help()`` returns true, will call + ``PrettyHelp::log_help()`` + + + traverse over the children of the root node and render as plain text + + effectively the reverse of converting unformatted ``Pass::help()`` text + + lines are broken at 80 characters while maintaining indentation (controlled + by ``MAX_LINE_LEN`` in :file:`kernel/log_help.cc`) + + each line is broken into words separated by spaces, if a given word starts + and ends with backticks they will be stripped + +- if it returns false it will call ``Pass::help()`` which should call ``log()`` + directly to print and format help text + + + if ``Pass::help()`` is not overridden then a default message about missing + help will be displayed + +.. literalinclude:: /generated/chformal.log + :lines: 2- + + +RST generated from autocmd +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- below is the raw RST output from ``autocmd`` (``YosysCmdDocumenter`` class in + :file:`docs/util/cmd_documenter.py`) for `chformal` command +- heading will be rendered as a subheading of the most recent heading (see + `chformal autocmd`_ above rendered under `Command help`_) +- ``.. cmd:def:: `` line is indexed for cross references with ``:cmd:ref:`` + directive (`chformal autocmd`_ above uses ``:noindex:`` option so that + `chformal` still links to the correct location) + + + ``:title:`` option controls text that appears when hovering over the + `chformal` link + +- commands with warning flags (experimental or internal) add a ``.. warning`` + block before any of the help content +- if a command has no ``source_location`` the ``.. note`` at the bottom will + instead link to :doc:`/cmd/index_other` + +.. autocmd_rst:: chformal + + +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 `` + + - prints help message for ```` + - constructed from ``SimHelper`` content depending on version + +- ``help +`` + + - prints verilog code for ```` + +v1 (default) +~~~~~~~~~~~~ + +- Legacy format +- Expects formatting as follows: + +.. code-block:: verilog + + //- + //- $ () + //* group + //- + //- + //- + module \$ (); + // ... + 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 (``//- $ ()``) 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 + + //* + +- ``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 diff --git a/docs/source/yosys_internals/extending_yosys/index.rst b/docs/source/yosys_internals/extending_yosys/index.rst index 72843ecd6..3b8aad541 100644 --- a/docs/source/yosys_internals/extending_yosys/index.rst +++ b/docs/source/yosys_internals/extending_yosys/index.rst @@ -13,5 +13,6 @@ of interest for developers looking to customise Yosys builds. functional_ir advanced_bugpoint contributing + documenting test_suites