From 0a6ce3d820349dfb2a7e840f0104030e2fbc3c57 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Sat, 15 Nov 2025 11:54:42 +1300 Subject: [PATCH] documenting.rst: formatted_help --- .../extending_yosys/documenting.rst | 155 +++++++++++++----- 1 file changed, 113 insertions(+), 42 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/documenting.rst b/docs/source/yosys_internals/extending_yosys/documenting.rst index 431c5ddda..67b3383aa 100644 --- a/docs/source/yosys_internals/extending_yosys/documenting.rst +++ b/docs/source/yosys_internals/extending_yosys/documenting.rst @@ -22,15 +22,16 @@ Command help ------------ The first stop for command help text is the ``Pass::short_help``. This is a -short sentence describing the pass, and is set in the ``Pass`` constructor, as -demonstrated here with `chformal`. +short sentence describing the pass, and is set in the ``Pass`` constructor with +the name of the pass, as demonstrated here with `chformal`. .. literalinclude:: /generated/chformal.cc :language: c++ :start-at: public Pass { - :end-before: bool formatted_help() + :end-at: ChformalPass() :caption: ``ChformalPass()`` from :file:`passes/cmds/chformal.cc` - :append: // ... + :append: + // ... } ChformalPass; All currently available commands are listed with their ``short_help`` string @@ -41,12 +42,19 @@ like :ref:`chformal autocmd`. The next section shows the complete help text for the `chformal` command. This can be displayed locally by using ``help `` (or ``yosys -h `` -from the command line). The general format is to show each usage signature, -followed by a paragraph describing what the pass does, and a list of options or -flags available. Additional arguments in the signature or option may use square -brackets (``[]``) to indicate optional parts, and angle brackets (``<>``) for -required parts. The pipe character ``|`` may be used to indicate mutually -exclusive arguments. +from the command line). The general format is to show each usage signature (how +the command is called), followed by a paragraph describing what the pass does, +and a list of options or flags available. Additional arguments in the signature +or option may use square brackets (``[]``) to indicate optional parts, and angle +brackets (``<>``) for required parts. The pipe character ``|`` may be used to +indicate mutually exclusive arguments. + +.. note:: + + Remember that when using ``Frontend`` and ``Backend`` the pass name will be + be prefixed with ``read_`` or ``write_`` respectively. Usage signatures must + match the pass name available in commands/scripts, which is available as + ``Pass::pass_name``. .. todo:: decide on a formatting style for pass options @@ -75,48 +83,70 @@ typically start with lower case, and may forgo a trailing period (``.``). Where multiple options share a description the blank line between options should be omitted. + The ``Pass::formatted_help()`` method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``PrettyHelp::get_current()`` -- ``PrettyHelp::set_group()`` +The ``formatted_help`` method serves two purposes in help generation, both of +which are optional. In both cases, any pass which uses the method should +``#include "kernel/log_help.h"``, and begin the method by calling ``auto *help = +PrettyHelp::get_current();``. The method finishes by returning a boolean value. +``true`` means help content has been added to the current ``PrettyHelp``, while +``false`` indicates that ``Pass::help()`` should be called instead. - + 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 +Setting a command group +^^^^^^^^^^^^^^^^^^^^^^^ -- return value +Command groups are used when `Dumping command help to json`_, so that related +commands can be presented together in documentation. For example, all of the +formal commands (which `chformal` is one of) are listed under +:doc:`/cmd/index_formal`, by using the ``autocmdgroup`` directive in +:file:`docs/source/cmd/index_formal.rst`. By default, commands are grouped by +their source location, such that the group is the same as the path to the source +file. - + true means help content added to current ``PrettyHelp`` - + false to use ``Pass::help()`` +.. note:: -- adding content + Source location tracking requires :makevar:`ENABLE_HELP_SOURCE` to be set in + the makefile. Some passes, like the ``opt_*`` family, are able to be grouped + by the name of the pass; but most will be assigned the ``unknown`` group. - + 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 + For frontends and backends, source code is structured such that different + formats are located in different folders. Default behavior is to instead + group all of these passes as :doc:`/cmd/index_frontends` and + :doc:`/cmd/index_backends` respectively. Without location tracking, the + fallback is to look for passes that start with ``read_`` or ``write_``. - * 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 +It is possible to set the group of a command explicitly with the +``PrettyHelp::set_group()`` method. This allows grouping of commands which may +not share a common source location, as well as ensuring that commands are still +grouped when location tracking is disabled. Because ``Pass::formatted_help()`` +returns if it produced help content, it is completely valid to override the +method, get the current instance of ``PrettyHelp``, set the command group, and +then return ``false``. - + ``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 +.. warning:: + + There is currently no warning available for groups that do not have a + corresponding ``autocmdgroup``. If you add a new command group, make sure + that it has a corresponding index page. + + +Rich help text +^^^^^^^^^^^^^^ + +The second purpose of ``Pass::formatted_help`` is to provide richer help +content which is able to take advantage of the reStructuredText formatting used +here in the web docs. It also provides a more fluid way of writing help text, +without getting caught up in the terminal-first spacing requirements of writing +for ``Pass::help()``. + +Help content is a list of ``ContentListing`` nodes on a root node, which can be +found by calling ``PrettyHelp::get_root()``. Each node has a type, a body, and +its own list of children ``ContentListing``\ s. Adding content is done with the +``ContentListing::{usage, option, codeblock, paragraph}`` methods, which each +add a new child node with a type set to the calling method. Let's take a look +at the source code for `chformal`. .. literalinclude:: /generated/chformal.cc :language: c++ @@ -124,6 +154,47 @@ The ``Pass::formatted_help()`` method :end-before: void execute :caption: ``ChformalPass::formatted_help()`` from :file:`passes/cmds/chformal.cc` +We can see that each of the ``ContentListing`` methods have the body of the new +node as the first argument. For a ``usage`` node, this is how to call the +command (i.e. its usage signature). ``paragraph`` nodes contain a paragraph of +text with line breaks added automatically; the argument itself should contain +any line breaks, but the string can be broken across multiple lines as shown. +The body of a ``paragraph`` node is treated as raw RST, allowing for inline +formatting and references as if it were written in the RST file itself. As +shown in the example (and the :ref:`formatted output above `), +this includes using single backticks for linking to cells or commands, and +double backticks for raw code. + +The ``option`` method lists a single option for the command, usually starting +with a dash (``-``). An optional second argument can be provided with adds a +paragraph node as a child of the option, and is used for describing the option. +Where multiple options share a description, it should be added to the last +option. + +.. note:: + + To add multiple paragraphs to an option's description, + ``ContentListing::open_option()`` should be used instead. This method + returns the option node, which can then be used to call + ``ContentList::paragraph()`` multiple times. + +``codeblock`` content is displayed verbatim, and content should include line +breaks as desired. No extra formatting will be applied to the text, and it will +be rendered with a monospace font; making it perfect for code sections or ASCII +art diagrams which render the same on the web as they do in the terminal. An +optional second argument is available for specifying the language in RST output +for code syntax highlighting (use ``yoscrypt`` for yosys script syntax +highlighting). + +.. + not recommended since it (currently) doesn't render in the terminal + + The final method available is ``ContentListing::open_usage``. As with + ``open_option`` creates and returns a new node which can have additional content + added to it directly. For the usage node, this can be used for example to add + text/options specific to a given usage of the command. In the web documentation + any content added in this way will be indented under the usage signature. + Dumping command help to json ~~~~~~~~~~~~~~~~~~~~~~~~~~~~