From 966f52e123e9e40a81b81bacec0696b8763db853 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Sat, 15 Nov 2025 16:06:09 +1300 Subject: [PATCH] documenting.rst: More json/sphinx bullets Also moved them to the bottom, instead of being under the "command help" heading. Now includes more info about cells, and the custom sphinx domains/directives/roles we have. --- .../extending_yosys/documenting.rst | 214 ++++++++++++------ 1 file changed, 146 insertions(+), 68 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/documenting.rst b/docs/source/yosys_internals/extending_yosys/documenting.rst index 67b3383aa..c0f51f637 100644 --- a/docs/source/yosys_internals/extending_yosys/documenting.rst +++ b/docs/source/yosys_internals/extending_yosys/documenting.rst @@ -83,6 +83,10 @@ 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. +.. note:: + + `Dumping to json`_ has more on how formatting in ``help()`` gets parsed. + The ``Pass::formatted_help()`` method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -97,7 +101,7 @@ PrettyHelp::get_current();``. The method finishes by returning a boolean value. Setting a command group ^^^^^^^^^^^^^^^^^^^^^^^ -Command groups are used when `Dumping command help to json`_, so that related +Command groups are used when `Dumping 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 @@ -196,51 +200,6 @@ highlighting). any content added in this way will be indented under the usage signature. -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 ~~~~~~~~~~~~~~~~~~~~~~ @@ -264,33 +223,16 @@ Command line rendering :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` + + + unlike commands, cell help text is generated at compile time + + only formatting occurs at run time + + no support for custom cells in plugins + - 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 @@ -299,6 +241,7 @@ Cell help - ``help -cells`` - lists all cells with their input/output ports + - again an unlisted :ref:`cell index ` - ``help `` @@ -424,3 +367,138 @@ v2 (more expressive) indentation and line length will be preserved, giving a scroll bar if necessary for the browser window more text + + +Dumping 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`). + + +Cells and commands in Sphinx +---------------------------- + +To support the rich documentation of commands and cells in Yosys, we use two +custom `Sphinx Domains`_. + +.. _Sphinx Domains: https://www.sphinx-doc.org/en/master/usage/domains/index.html + +- ``yoscrypt`` role allows inline code to have yosys script syntax highlighting +- default role of ``autoref`` + + + any text in single backticks without an explicit role will be assigned this one + + will convert to ``cell:ref`` if it begins with ``$``, otherwise ``cmd:ref`` + + to attempt linking there must be no spaces, and it must not begin with a + dash (``-``) + + ```chformal``` (or ``:autoref:`chformal```) -> ``:cmd:ref:`chformal``` -> `chformal` + + also works with two words, if the first one is ``help`` + + ```help $add``` -> ``:cell:ref:`help $add <$add>``` -> `help $add` + + fallback to formatting as inline yoscrypt + + ```-remove``` -> `-remove` + + ```chformal -remove``` -> ``:yoscrypt:`chformal -remove``` -> `chformal -remove` + +Using autodoc +~~~~~~~~~~~~~ + +- 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` + +.. _showing autocmd generated rst: + +.. autocmd_rst:: chformal + +- command groups documented with ``autocmdgroup `` + + + with ``:members:`` option this is the same as calling ``autocmd`` for each + member of the group + +- ``autocell`` and ``autocellgroup`` + + + very similar to ``autocmd`` and ``autocmdgroup`` but for cells instead of + commands (``YosysCellDocumenter`` in :file:`docs/util/cell_documenter.py`) + + optionally includes verilog source for cell(s) with ``:source:`` option + (plus ``:linenos:``) + + cell definitions do not include titles + + cells can have properties (:ref:`propindex`) + +- bonus ``autocmd_rst``, used exclusively on this page for `showing autocmd + generated rst`_ + +Our custom Sphinx domains +~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``cmd`` and ``cell`` +- Directives + + + ``cmd:def`` provide command definition + + ``cmd:usage`` used by ``autocmd`` for command usage signatures + + ``cell:def`` provide cell definition + + ``cell:defprop`` provide cell property definition (used in + :doc:`/cell/properties`) + + ``cell:source`` used by ``autocell`` for simulation models + +- Roles + + + ``cmd:ref`` link to a ``cmd:def`` with the same name + + ``cmd:title`` same as ``cmd:ref``, but includes the short help in the text + + - ``:cmd:title:`chformal``` -> :cmd:title:`chformal` + + + ``cell:ref`` link to a ``cell:def`` with the same name + + ``cell:title`` + + - ``:cell:title:`$nex``` -> :cell:title:`$nex` + + + ``cell:prop`` link to a ``cell:defprop`` of the same name