[PATCH] Improved reStructuredText formatting of Misra C Rules

[Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>]

Code blocks in the RFC rules can be converted as C syntax-highlighted
pretty pieces of code using `.. code:: C` inline elements:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#code

For reference, the current formatting used are 'Indented Literal Blocks':
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#toc-entry-23

In this example, docs/misra/rules.rst, line 128 starts an Indented
Literal Block by ending the paragraph with "violations::"
(note the :: at then end of the paragraph which is enables it):

         - Functions that are no-return due to calls to the 
`ASSERT_UNREACHABLE()`
           macro in debug build configurations are not considered violations::

              static inline bool
              arch_vcpu_ioreq_completion(enum vio_completion completion)
              {
                  ASSERT_UNREACHABLE();
                  return false;
              }

Format such code blocks as C code blocks and apply ``function()`` around
functions to make them inline linterals for monospace formatting.
Also make some code blocks less wide to fit into the column of the table.

Signed-off-by: Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>
---
Of course, this is only a 1st step,
it may be extended further in further merges.

Preview based on the theme update submitted yesterday:
https://lists.xen.org/archives/html/xen-devel/2026-04/msg01375.html:

https://bernhard-xen.readthedocs.io/en/misra-rules-format-rfc/misra/rules.html

BTW: The way the ReadTheDocs (RTD) theme has another issue where it
applies: 'td { white-space: nowrap; }' to all table data,
preventing wrapping lines inside long table cells:
https://xenbits.xen.org/docs/sphinx-unstable/misra/rules.html

This mostly shows on xenbits for me, but this is a widely known RTD bug.
The RTD Sphinx devs see this bug as a feature, and are unwilling to fix:
https://github.com/readthedocs/sphinx_rtd_theme/issues/139 (example bug)

There are workarounds, but to better address this 1st step, I propose to
add a theme which does not appear to have this issue (and also has a
more modern look and feel with auto dark mode support (can be switched
to bright mode and darm mode directly as well):

https://lists.xen.org/archives/html/xen-devel/2026-04/msg01375.html
Signed-off-by: Bernhard Kaindl <bernhard.kaindl@xxxxxxxxxx>
---
 docs/misra/rules.rst | 43 ++++++++++++++++++++++++++++---------------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
index fc6fdfd313d0..82412e819846 100644
--- a/docs/misra/rules.rst
+++ b/docs/misra/rules.rst
@@ -115,20 +115,29 @@ maintainers if you want to suggest a change.
      - Required
      - A project shall not contain unreachable code
      - The following are allowed:
-         - Invariantly constant conditions, e.g. if(IS_ENABLED(CONFIG_HVM)) { 
S; }
+         - Invariantly constant conditions, e.g.
+
+           .. code:: C
+
+              if ( IS_ENABLED(CONFIG_HVM) ) {
+                S;
+              }
+
          - Switch with a controlling value statically determined not to
            match one or more case statements
          - Functions that are intended to be referenced only from
-           assembly code (e.g. 'do_trap_fiq')
-         - asm-offsets.c, as they are not linked deliberately, because
+           assembly code (e.g. ``do_trap_fiq``)
+         - ``asm-offsets.c``, as they are not linked deliberately, because
            they are used to generate definitions for asm modules
          - Declarations without initializer are safe, as they are not
            executed
-         - Functions that are no-return due to calls to the 
`ASSERT_UNREACHABLE()`
-           macro in debug build configurations are not considered violations::
+         - Functions that are no-return due to calls to the 
``ASSERT_UNREACHABLE()``
+           macro in debug build configurations are not considered violations:
+
+           .. code:: C
 
               static inline bool
-              arch_vcpu_ioreq_completion(enum vio_completion completion)
+              arch_vcpu_ioreq_completion(int c)
               {
                   ASSERT_UNREACHABLE();
                   return false;
@@ -141,13 +150,13 @@ maintainers if you want to suggest a change.
 
    * - `Rule 3.1 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_01.c>`_
      - Required
-     - The character sequences /* and // shall not be used within a
+     - The character sequences ``/*`` and ``//`` shall not be used within a
        comment
      - Comments containing URLs inside C-style block comments are safe
 
    * - `Rule 3.2 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_03_02.c>`_
      - Required
-     - Line-splicing shall not be used in // comments
+     - Line-splicing shall not be used in ``//`` comments
      -
 
    * - `Rule 4.1 
<https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_04_01.c>`_
@@ -207,16 +216,20 @@ maintainers if you want to suggest a change.
 
        Clashes between bitops functions and macro names are allowed
        because they are used for input validation and error handling.
-       Example::
+       Example:
 
-           static inline void set_bit(int nr, volatile void *addr)
+       .. code:: C
+
+           static inline void set_bit(int nr, volatile void *a)
            {
-               asm volatile ( "lock btsl %1,%0"
-                              : "+m" (ADDR) : "Ir" (nr) : "memory");
+               asm volatile ( "lock btsl %1,%0 "
+                              : "+m" (a)
+                              : "Ir" (nr) : "memory");
            }
-           #define set_bit(nr, addr) ({                            \
-               if ( bitop_bad_size(addr) ) __bitop_bad_size();     \
-               set_bit(nr, addr);                                  \
+
+           #define set_bit(nr, addr) ({                       \
+               if ( bitop_bad_size(addr) ) __bitop_bad_size();\
+               set_bit(nr, addr);                             \
            })
 
        Clashes between grant table functions and macro names are allowed
-- 
2.39.5