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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 15/08/2025 8:28 am, Dmytro Prokopchuk1 wrote:
>
> 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>

Reviewed-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>

>>
>> I recall that Andrew wanted to add a doc build test to avoid introducing 
>> warnings.

Yes I do, but sadly still on my TODO list.

>>  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.

IIRC, this needs ignoring for now.  It is still required in the minimum
Sphinx version we support.

~Andrew