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

[PATCH v2] 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]
4. remove backticks from references to source code in the file rules.rst
to have a consistent style in this file

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>
---
Link to v1:
https://patchew.org/Xen/fb809a94e8a50bd3a59aa47ee1832c61af8a9f40.1755241166.git.dmytro._5Fprokopchuk1@epam.com/

Changes in v2:
- updated commit message (item 4)
- added review tags
- in the file rules.rst, removed backticks from references to source code
---
 docs/misra/deviations.rst | 3 ++-
 docs/misra/rules.rst      | 8 ++++----
 2 files changed, 6 insertions(+), 5 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..be315bc991 100644
--- 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)
          - asm-offsets.c, as they are not linked deliberately, because
            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
@@ -413,8 +413,8 @@ maintainers if you want to suggest a change.
        and any other type
      - All conversions to integer types are permitted if the destination
        type has enough bits to hold the entire value. Conversions to bool
-       and void* are permitted. Conversions from 'void noreturn (*)(...)'
-       to 'void (*)(...)' are permitted.
+       and void* are permitted. Conversions from void noreturn (*)(...)
+       to void (*)(...) are permitted.
 
    * - `Rule 11.2 <https://gitlab.com/MISRA/MISRA-C/MISRA-C-2012/Example-Suite/-/blob/master/R_11_02.c>`_
      - Required
-- 
2.43.0

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

Posted by Jan Beulich 2 months, 1 week ago

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

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

Posted by Dmytro Prokopchuk1 2 months, 1 week ago


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.