Sphinx supports the :kbd: role for notating keyboard input. They get
formatted as <kbd> HTML elements in the readthedocs theme we currently
use for Sphinx.

Besides the better visual formatting, it also helps with accessibility
as screen readers can announce the semantics of the <kbd> element to the
user.

Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
---
Changes in v2:
- Formatted multiplexer key list as a table (suggested by Alex)
- Link to v1: https://lore.kernel.org/qemu-devel/20250703-docs_rst_improvements-v1-1-0dbbc5eb5871@linaro.org
---
 docs/devel/testing/main.rst     |  4 ++--
 docs/system/images.rst          |  2 +-
 docs/system/keys.rst.inc        | 49 +++++++++++++++++++++--------------------
 docs/system/linuxboot.rst       |  2 +-
 docs/system/mux-chardev.rst.inc | 38 ++++++++++++++++++--------------
 5 files changed, 51 insertions(+), 44 deletions(-)

diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
index 6b18ed875cd91e961d07b3afa3179c7fba0e5fe3..2b5cb0c148048e3a81d2db8c4a9500591880997f 100644
--- a/docs/devel/testing/main.rst
+++ b/docs/devel/testing/main.rst
@@ -604,9 +604,9 @@ below steps to debug it:
 2. Add "V=1" to the command line, try again, to see the verbose output.
 3. Further add "DEBUG=1" to the command line. This will pause in a shell prompt
    in the container right before testing starts. You could either manually
-   build QEMU and run tests from there, or press Ctrl-D to let the Docker
+   build QEMU and run tests from there, or press :kbd:`Ctrl+d` to let the Docker
    testing continue.
-4. If you press Ctrl-D, the same building and testing procedure will begin, and
+4. If you press :kbd:`Ctrl+d`, the same building and testing procedure will begin, and
    will hopefully run into the error again. After that, you will be dropped to
    the prompt for debug.
 
diff --git a/docs/system/images.rst b/docs/system/images.rst
index a5551173c9789323ceb150c51fd68c6d4ef80d71..43706969fddae7bcb83de172b1a04b5c6cffe0f1 100644
--- a/docs/system/images.rst
+++ b/docs/system/images.rst
@@ -30,7 +30,7 @@ Snapshot mode
 If you use the option ``-snapshot``, all disk images are considered as
 read only. When sectors in written, they are written in a temporary file
 created in ``/tmp``. You can however force the write back to the raw
-disk images by using the ``commit`` monitor command (or C-a s in the
+disk images by using the ``commit`` monitor command (or :kbd:`Ctrl+a s` in the
 serial console).
 
 .. _vm_005fsnapshots:
diff --git a/docs/system/keys.rst.inc b/docs/system/keys.rst.inc
index 59966a3fe7cf2cbb6a19dacd48612b768b7a1e96..c28ae1a2272707d292a159c2650bd6bf6a4c1e19 100644
--- a/docs/system/keys.rst.inc
+++ b/docs/system/keys.rst.inc
@@ -1,36 +1,37 @@
 During the graphical emulation, you can use special key combinations from
-the following table to change modes. By default the modifier is Ctrl-Alt
+the following table to change modes. By default the modifier is :kbd:`Ctrl+Alt`
 (used in the table below) which can be changed with ``-display`` suboption
 ``mod=`` where appropriate. For example, ``-display sdl,
-grab-mod=lshift-lctrl-lalt`` changes the modifier key to Ctrl-Alt-Shift,
-while ``-display sdl,grab-mod=rctrl`` changes it to the right Ctrl key.
+grab-mod=lshift-lctrl-lalt`` changes the modifier key to :kbd:`Ctrl+Alt+Shift`,
+while ``-display sdl,grab-mod=rctrl`` changes it to the right :kbd:`Ctrl` key.
 
-Ctrl-Alt-f
-   Toggle full screen
+.. list-table:: Multiplexer Keys
+  :widths: 10 90
+  :header-rows: 1
 
-Ctrl-Alt-+
-   Enlarge the screen
+  * - Key Sequence
+    - Action
 
-Ctrl-Alt\--
-   Shrink the screen
+  * - :kbd:`Ctrl+Alt+f`
+    - Toggle full screen
 
-Ctrl-Alt-u
-   Restore the screen's un-scaled dimensions
+  * - :kbd:`Ctrl+Alt++`
+    - Enlarge the screen
 
-Ctrl-Alt-n
-   Switch to virtual console 'n'. Standard console mappings are:
+  * - :kbd:`Ctrl+Alt+-`
+    - Shrink the screen
 
-   *1*
-      Target system display
+  * - :kbd:`Ctrl+Alt+u`
+    - Restore the screen's un-scaled dimensions
 
-   *2*
-      Monitor
+  * - :kbd:`Ctrl+Alt+n`
+    - Switch to virtual console 'n'. Standard console mappings are:
 
-   *3*
-      Serial port
+      - *1*: Target system display
+      - *2*: Monitor
+      - *3*: Serial port
+  * - :kbd:`Ctrl+Alt+g`
+    - Toggle mouse and keyboard grab.
 
-Ctrl-Alt-g
-   Toggle mouse and keyboard grab.
-
-In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and
-Ctrl-PageDown to move in the back log.
+In the virtual consoles, you can use :kbd:`Ctrl+Up`, :kbd:`Ctrl+Down`, :kbd:`Ctrl+PageUp` and
+:kbd:`Ctrl+PageDown` to move in the back log.
diff --git a/docs/system/linuxboot.rst b/docs/system/linuxboot.rst
index 2328b4a73d55b47d731497d57ddb1a837ef5d7dd..f7573ab80aa269bac870d7e6e5596a8f02fbd5f3 100644
--- a/docs/system/linuxboot.rst
+++ b/docs/system/linuxboot.rst
@@ -26,5 +26,5 @@ virtual serial port and the QEMU monitor to the console with the
    |qemu_system| -kernel bzImage -drive file=rootdisk.img,format=raw \
                     -append "root=/dev/sda console=ttyS0" -nographic
 
-Use Ctrl-a c to switch between the serial console and the monitor (see
+Use :kbd:`Ctrl+a c` to switch between the serial console and the monitor (see
 :ref:`GUI_keys`).
diff --git a/docs/system/mux-chardev.rst.inc b/docs/system/mux-chardev.rst.inc
index 84ea12cbf58f9550154411f8951e6f608179a091..c87ba31362965c4e06d892217df7fedebcb3092c 100644
--- a/docs/system/mux-chardev.rst.inc
+++ b/docs/system/mux-chardev.rst.inc
@@ -1,27 +1,33 @@
 During emulation, if you are using a character backend multiplexer
 (which is the default if you are using ``-nographic``) then several
 commands are available via an escape sequence. These key sequences all
-start with an escape character, which is Ctrl-a by default, but can be
+start with an escape character, which is :kbd:`Ctrl+a` by default, but can be
 changed with ``-echr``. The list below assumes you're using the default.
 
-Ctrl-a h
-   Print this help
+.. list-table:: Multiplexer Keys
+  :widths: 20 80
+  :header-rows: 1
 
-Ctrl-a x
-   Exit emulator
+  * - Key Sequence
+    - Action
 
-Ctrl-a s
-   Save disk data back to file (if -snapshot)
+  * - :kbd:`Ctrl+a h`
+    - Print this help
 
-Ctrl-a t
-   Toggle console timestamps
+  * - :kbd:`Ctrl+a x`
+    - Exit emulator
 
-Ctrl-a b
-   Send break (magic sysrq in Linux)
+  * - :kbd:`Ctrl+a s`
+    - Save disk data back to file (if -snapshot)
 
-Ctrl-a c
-   Rotate between the frontends connected to the multiplexer (usually
-   this switches between the monitor and the console)
+  * - :kbd:`Ctrl+a t`
+    - Toggle console timestamps
 
-Ctrl-a Ctrl-a
-   Send the escape character to the frontend
+  * - :kbd:`Ctrl+a b`
+    - Send break (magic sysrq in Linux)
+
+  * - :kbd:`Ctrl+a c`
+    - Rotate between the frontends connected to the multiplexer (usually this switches between the monitor and the console)
+
+  * - :kbd:`Ctrl+a Ctrl+a`
+    - Send the escape character to the frontend

---
base-commit: df6fe2abf2e990f767ce755d426bc439c7bba336
change-id: 20250703-docs_rst_improvements-1f0cb3c578d6

--
γαῖα πυρί μιχθήτω

Manos Pitsidianakis <manos.pitsidianakis@linaro.org> writes:

> Sphinx supports the :kbd: role for notating keyboard input. They get
> formatted as <kbd> HTML elements in the readthedocs theme we currently
> use for Sphinx.
>
> Besides the better visual formatting, it also helps with accessibility
> as screen readers can announce the semantics of the <kbd> element to the
> user.
>
> Signed-off-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>

Queued to docs/next, thanks.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro