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

[Dmytro Prokopchuk1 <dmytro_prokopchuk1@xxxxxxxx>]

On 8/18/25 10:38, Jan Beulich wrote:
> 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

As I mentioned before, these files (deviations.rst and rules.rst) have 
mixed style of quotes.
The rules.rst has three places:
1. 'do_trap_fiq'
2. `ASSERT_UNREACHABLE()`
3. 'void noreturn (*)(...)', 'void (*)(...)'
Because ASSERT_UNREACHABLE is used with backticks in the deviations.rst, 
it should have backticks in rules.rst also (I hope).
But #1 and #3 have single quotes -> mixed style.
So, I decided to remove all quotes in this rules.rst file.

I didn't touch deviations.rst, because it will be a mess.

Dmytro.