Re: [PATCH v2] docs/misra: fix sphinx-build issues

[Jan Beulich <jbeulich@xxxxxxxx>]

On 15.08.2025 16:15, Dmytro Prokopchuk1 wrote:
> Fix the following issues:
> 1. xen/docs/misra/deviations.rst:90: WARNING: Inline interpreted text or
> phrase reference start-string without end-string. [docutils]
> 2. xen/docs/misra/deviations.rst:54: ERROR: Error parsing content block
> for the "list-table" directive: uniform two-level bullet list expected,
> but row 6 does not contain the same number of items as row 1 (2 vs 3).
> * - R2.1
>   - Calls to the `__builtin_unreachable()` function inside the expansion of
>     the `ASSERT_UNREACHABLE()` macro may cause a function to be marked as
>     non-returning. This behavior occurs only in configurations where
>     assertions are enabled. To address this, the `noreturn` property for
>     `__builtin_unreachable()` is overridden in these contexts, resulting in
>     the absence of reports that do not have an impact on safety, despite
>     being true positives.
>     Xen expects developers to ensure code remains safe and reliable in builds,
>     even when debug-only assertions like `ASSERT_UNREACHABLE() are removed.
> 3. xen/docs/misra/rules.rst:127: WARNING: Inline interpreted text or phrase
> reference start-string without end-string. [docutils]
> 4. remove backticks from references to source code in the file rules.rst
> to have a consistent style in this file

I don't understand this: For one, why remove quotation? Personally I
consider such quoting useful. And then ...

> --- a/docs/misra/deviations.rst
> +++ b/docs/misra/deviations.rst
> @@ -95,7 +95,8 @@ Deviations related to MISRA C:2012 Rules:
>         the absence of reports that do not have an impact on safety, despite
>         being true positives.
>         Xen expects developers to ensure code remains safe and reliable in 
> builds,
> -       even when debug-only assertions like `ASSERT_UNREACHABLE() are 
> removed.
> +       even when debug-only assertions like `ASSERT_UNREACHABLE()` are 
> removed.
> +     - ECLAIR has been configured to ignore those statements.

... backticks are still kept here (kind of in line with what you say in
4, but still somewhat puzzling). Whereas what you remove ...

> --- a/docs/misra/rules.rst
> +++ b/docs/misra/rules.rst
> @@ -119,12 +119,12 @@ maintainers if you want to suggest a change.
>           - 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')
> +           assembly code (e.g. do_trap_fiq)

... e.g. here are single quotes.

Jan