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

[Dmytro Prokopchuk1 <dmytro_prokopchuk1@xxxxxxxx>]

On 8/15/25 10:09, Nicola Vetrini wrote:
> On 2025-08-15 09:00, 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]
>>
>> Signed-off-by: Dmytro Prokopchuk <dmytro_prokopchuk1@xxxxxxxx>
> 
> Reviewed-by: Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx>
> 
> I recall that Andrew wanted to add a doc build test to avoid introducing 
> warnings. On that front, with my Sphinx version I also see this build 
> warning:
> 
> Running Sphinx v8.1.3
> WARNING: Calling get_html_theme_path is deprecated. If you are calling 
> it to define html_theme_path, you are safe to remove that code.
> 
Yes, I see the same warning on my end.
Need to address that in docs/conf.py as well.

Dmytro.
>> ---
>>  docs/misra/deviations.rst | 3 ++-
>>  docs/misra/rules.rst      | 2 +-
>>  2 files changed, 3 insertions(+), 2 deletions(-)
>>
>> diff --git a/docs/misra/deviations.rst b/docs/misra/deviations.rst
>> index 3c46a1e47a..2be49076e1 100644
>> --- 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.
>>
>>     * - R2.2
>>       - Proving compliance with respect to Rule 2.2 is generally 
>> impossible:
>> diff --git a/docs/misra/rules.rst b/docs/misra/rules.rst
>> index 6812eb7e8a..382331447e 100644
>> --- a/docs/misra/rules.rst
>> +++ b/docs/misra/rules.rst
>> @@ -124,7 +124,7 @@ maintainers if you want to suggest a change.
>>             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()'
>> +         - Functions that are no-return due to calls to the 
>> 'ASSERT_UNREACHABLE()'
>>             macro in debug build configurations are not considered 
>> violations::
>>
>>                static inline bool
>