1. Patchew
  2. Xen
  3. View series

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

Dmytro Prokopchuk1 posted 1 patch 2 months, 2 weeks ago
Patches applied successfully (tree, apply log)
git fetch https://gitlab.com/xen-project/patchew/xen tags/patchew/fb809a94e8a50bd3a59aa47ee1832c61af8a9f40.1755241166.git.dmytro._5Fprokopchuk1@epam.com
There is a newer version of this series
docs/misra/deviations.rst | 3 ++-
docs/misra/rules.rst      | 2 +-
2 files changed, 3 insertions(+), 2 deletions(-)
[PATCH] docs/misra: fix sphinx-build issues
Posted by Dmytro Prokopchuk1 2 months, 2 weeks ago 
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@epam.com>
---
 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
-- 
2.43.0
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Jan Beulich 2 months, 2 weeks ago 
On 15.08.2025 09:00, Dmytro Prokopchuk1 wrote:
> --- 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.

Mind me asking why one form of quoting is used here (using back-tick), while ...

> --- 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()'

... another is used here (single quotes)?

Jan
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Dmytro Prokopchuk1 2 months, 2 weeks ago 

On 8/15/25 11:42, Jan Beulich wrote:
> On 15.08.2025 09:00, Dmytro Prokopchuk1 wrote:
>> --- 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.
> 
> Mind me asking why one form of quoting is used here (using back-tick), while ...
> 
>> --- 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()'
> 
> ... another is used here (single quotes)?
> 
> Jan

Good question...
I'll align a style.

Dmytro.
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Dmytro Prokopchuk1 2 months, 2 weeks ago 

On 8/15/25 13:30, Dmytro Prokopchuk wrote:
> 
> 
> On 8/15/25 11:42, Jan Beulich wrote:
>> On 15.08.2025 09:00, Dmytro Prokopchuk1 wrote:
>>> --- 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.
>>
>> Mind me asking why one form of quoting is used here (using back-tick), 
>> while ...
>>
>>> --- 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()'
>>
>> ... another is used here (single quotes)?
>>
>> Jan
> 
> Good question...
> I'll align a style.
> 
> Dmytro.

Well, the deviations.rst and rules.rst files have a mixed style.
Sometimes file names are in '', and sometimes in ``.
The same inconsistency applies to referring to code.

Any style suggestions?

Dmytro.
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Jan Beulich 2 months, 2 weeks ago 
On 15.08.2025 14:42, Dmytro Prokopchuk1 wrote:
> On 8/15/25 13:30, Dmytro Prokopchuk wrote:
>> On 8/15/25 11:42, Jan Beulich wrote:
>>> On 15.08.2025 09:00, Dmytro Prokopchuk1 wrote:
>>>> --- 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.
>>>
>>> Mind me asking why one form of quoting is used here (using back-tick), 
>>> while ...
>>>
>>>> --- 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()'
>>>
>>> ... another is used here (single quotes)?
>>>
>>> Jan
>>
>> Good question...
>> I'll align a style.
>>
>> Dmytro.
> 
> Well, the deviations.rst and rules.rst files have a mixed style.
> Sometimes file names are in '', and sometimes in ``.
> The same inconsistency applies to referring to code.
> 
> Any style suggestions?

That depends on how both quoting styles are treated by Sphinx. Which is
something I don't know. I merely noticed the inconsistency within this
single patch.

Jan
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Nicola Vetrini 2 months, 2 weeks ago 
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@epam.com>

Reviewed-by: Nicola Vetrini <nicola.vetrini@bugseng.com>

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
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Dmytro Prokopchuk1 2 months, 2 weeks ago 

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@epam.com>
> 
> Reviewed-by: Nicola Vetrini <nicola.vetrini@bugseng.com>
> 
> 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
>
Re: [PATCH] docs/misra: fix sphinx-build issues
Posted by Andrew Cooper 2 months, 2 weeks ago 
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@epam.com>
>> Reviewed-by: Nicola Vetrini <nicola.vetrini@bugseng.com>

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

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

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.