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

[Nicola Vetrini <nicola.vetrini@xxxxxxxxxxx>]

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.
> ---
>  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
--
Nicola Vetrini, B.Sc.
Software Engineer
BUGSENG (https://bugseng.com)
LinkedIn: https://www.linkedin.com/in/nicola-vetrini-a42471253