Incorrect Interpretation of [[...]] Syntax in .. code-block:: (interpreted as dynamic function) within needs

[JensKlimke]

Use-case:

When documenting function signatures in C++ using the .. code-block:: directive in Sphinx-Needs, the attribute [[nodiscard]] (or similar double square bracket syntax) is incorrectly interpreted as a dynamic function by Sphinx-Needs. This results in a rendering error, where Sphinx attempts to process the content inside the [[...]] as a special directive or function, rather than rendering it as plain text within the code block.

Steps to Reproduce:

1. Use the following block in an RST file:

   .. spec:: Program flow for subtraction method
     :status: open
   
     ..  code-block:: cpp
   
         \[[nodiscard]\] SomeStruct getInformation() const;
   
     This method shall return the information vector of the class.

2. Build the documentation with Sphinx-Needs.

Expected Behavior:

The [[nodiscard]] attribute should be rendered exactly as it appears in the source code, without any modification or interpretation by Sphinx-Needs.

Actual Behavior:

Sphinx-Needs interprets [[nodiscard]] as a dynamic function, causing the documentation to either fail to render correctly or produce unintended results.

  sphinx error:
  Given dynamic function string is not a valid python call. Got: nodiscard

Workarounds Tried:

• Escaping the square brackets using \[\[nodiscard\]\] or \[[nodiscard]\] results in the backslashes being rendered in the output, which is not the desired behavior.

Environment:

• Sphinx Version: [7.1.0]
• Sphinx-Needs Version: [3.0.0]
• Python Version: [3.12.4]
• Operating System: [macOS]

Additional Information:

This issue seems specific to Sphinx-Needs' handling of the [[...]] syntax in code blocks. It might be related to the processing of inline directives or dynamic functions within the documentation build process.

Suggested Fix:

A potential fix could involve updating the parser to ignore [[...]] within .. code-block:: or include an escaping mechanism.

[chrisjsewell]

heya @JensKlimke, yes I agree, I am not a fan of this dynamic function syntax at all.

The code at issue is here: https://github.com/useblocks/sphinx-needs/blob/32fd0b51e22d06604eaaea77eae2825676dd73f5/sphinx_needs/functions/functions.py#L114

you could skip literal_block nodes and/or allow for escaping, but honestly I feel it would be much better (and less surprising to users), to just remove this [[..]] parsing and let users instead use a role similar to https://sphinx-needs.readthedocs.io/en/latest/roles.html#need-func, for a singular dynamic function that can "detect" the need it is defined in, e.g. something like :need_df:`echo("first")`

[chrisjsewell]

as a note-to-self for another this feature does not work as expected:

.. req:: Test
   :id: test
   :status: open

   This is a test requirement.

   .. req:: Test 2
      :id: test2
      :status: open

      [[func(...)]]

The func would actually be passed the outer test need, rather than the inner test2 need

[ubmarco]

This is more or less a duplicate of https://github.com/useblocks/sphinx-needs/issues/1199, just for a different language.