From 0fab912005d82bcd1d0d450118b06d57cd21d8d1 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 10 Jun 2024 18:46:31 +1200
Subject: [PATCH] Docs: Use sby role shortcut

---
 docs/source/reference.rst | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/docs/source/reference.rst b/docs/source/reference.rst
index 68da65d..8329d3e 100644
--- a/docs/source/reference.rst
+++ b/docs/source/reference.rst
@@ -1,17 +1,21 @@
+.. role:: sby(code)
+   :language: sby
 
 Reference for .sby file format
 ==============================
 
 A ``.sby`` file consists of sections. Each section start with a single-line
-section header in square brackets. The order of sections in a ``.sby`` file
-is for the most part irrelevant, but by convention the usual order is
-``[tasks]``, ``[options]``, ``[engines]``, ``[script]``,  and ``[files]``.
+section header in square brackets. The order of sections in a ``.sby`` file is
+for the most part irrelevant, but by convention the usual order is
+:sby:`[tasks]`, :sby:`[options]`, :sby:`[engines]`, :sby:`[script]`,  and
+:sby:`[files]`.
 
 Tasks section
 -------------
 
-The optional ``[tasks]`` section can be used to configure multiple verification tasks in
-a single ``.sby`` file. Each line in the ``[tasks]`` section configures one task. For example:
+The optional :sby:`[tasks]` section can be used to configure multiple
+verification tasks in a single ``.sby`` file. Each line in the :sby:`[tasks]`
+section configures one task. For example:
 
 .. code-block:: sby
 
@@ -30,9 +34,9 @@ calling ``sby`` on a ``.sby`` file:
 
    sby example.sby task2
 
-If no task is specified then all tasks in the ``[tasks]`` section are run.
+If no task is specified then all tasks in the :sby:`[tasks]` section are run.
 
-After the ``[tasks]`` section individual lines can be specified for specific
+After the :sby:`[tasks]` section individual lines can be specified for specific
 tasks or task groups:
 
 .. code-block:: sby
@@ -101,7 +105,7 @@ combinations of some host implementations A and B and device implementations X a
    deviceY: read -sv deviceY.v
    ...
 
-The ``[tasks]`` section must appear in the ``.sby`` file before the first
+The :sby:`[tasks]` section must appear in the ``.sby`` file before the first
 ``<taskname>:`` or ``~<taskname>:`` tag.
 
 The command ``sby --dumptasks <sby_file>`` prints the list of all tasks defined in
@@ -110,7 +114,7 @@ a given ``.sby`` file.
 Options section
 ---------------
 
-The ``[options]`` section contains lines with key-value pairs. The ``mode``
+The :sby:`[options]` section contains lines with key-value pairs. The ``mode``
 option is mandatory. The possible values for the ``mode`` option are:
 
 ========= ===========
@@ -374,7 +378,7 @@ other engines. This makes it easier to use the same models outside of sby.
 Script section
 --------------
 
-The ``[script]`` section contains the Yosys script that reads and elaborates
+The :sby:`[script]` section contains the Yosys script that reads and elaborates
 the design under test. For example, for a simple project contained in a single
 design file ``mytest.sv`` with the top-module ``mytest``:
 
@@ -447,8 +451,8 @@ File sections
 -------------
 
 File sections can be used to create additional files in ``<outdir>/src/`` from
-the literal content of the ``[file <filename>]`` section ("here document"). For
-example:
+the literal content of the :sby:`[file <filename>]` section ("here document").
+For example:
 
 .. code-block:: sby