Errors in sphinx-needs directives only show with source rst_prolog

[arwedus]

Observed behavior

Example warning:

File "workspace/.sphinx-venv/lib/python3.8/site-packages/sphinx/util/logging.py", line 425, in filter
    raise exc
sphinx.errors.SphinxWarning: <rst_prolog>:9:Error in "image" directive:
no content permitted.

.. image:: img/accelerationTransfIDS_.*

 The acceleration vector is transformed from VEH in IDS coordinate system using the Direction Matrix defined in REQ_SW_VSEc_Uc_008.

Warning, treated as error:
<rst_prolog>:9:Error in "image" directive:
no content permitted.

The example document:

.. req-sw:: The VSE shall provide the acceleration transformation of a particular vehicle position from the vehicle into the IDS coordinate system.
   :id: REQ_SW_VSEc_Uc_013
   :status: draft

   *Use Case*:
      bla bla bla

   .. image:: img/accelerationTransfIDS_.*

    The acceleration vector is transformed from VEH in IDS coordinate system using the Direction Cosine Matric defined in REQ_SW_VSEc_Uc_008.

In the example above, the warning context makes it possible to find the source, but it's not always so easy. E.g., in the following real-world example, the context is completely lost:

 Warning, treated as error:
<rst_prolog>:9:Line block ends without a blank line.

Expected Behavior

I'm not sure if this is general sphinx behavior or sphinx-needs specific, but ideally the file where the warning comes from is given in the pointy brackets, just as with reStructuredText warnings outside of a directive.

[danwos]

Thanks for reporting. :+1:

That's a tough one because the content of a Sphinx-Needs node gets rendered by Sphinx internally outside the document. So it only knows the "outer" directive (here Sphinx-Need node) and its line number.

I have to check, if we can give Sphinx render-function a parameter, which defines where the linenumber starts so that it calculates the right ones.

---

I hope I got your point, as for me

ideally the file where the warning comes from is given in the pointy brackets, just as with reStructuredText warnings outside of a directive.

is given this way or not?

<rst_prolog>:9:Line block ends without a blank line.

[arwedus]

<rst_prolog> is not a document though... i.e. in this case, the containing document was lost

[arwedus]

@danwos any updates to this request? We had yet another case of wasted hours because of trying to find the source of a new sphinx-warning with this code:

.. req:: Central Vehicle Time
  :id: REQ_KIT_TS_095
  :status: draft

  CVT shall support two modes for measuring elapsed real time:

  - Mode 1: Normal Operation
  - Mode 2 (Special Conditions):
    Mode 2 = In case UTC is not available due to any reason or there is leap second

  Note:

  - See :need:`REQ_KIT_TS_008` for Mode 1.
  - See :need:`REQ_KIT_TS_096`for Mode 2.

Can you find the source of the <rst_prolog>:7: WARNING: Inline interpreted text or phrase reference start-string without end-string.? 🙂

If you pull the "Note" list out, it will become clear, e.g.: time_sync_requirements_viewpoint.rst:260: WARNING: Inline interpreted text or phrase reference start-string without end-string..

Imagine trying to find this in a requirements spec with 1000 lines, and how much time would you estimate for that? 🙂

So... if at least the needs ID from which the warning originates would be known, this would be a huge time saver.

[danwos]

We have to check:

1. Can we catch the rendering exception?
2. If yes, output also the current file, need-id, need-line-number in an extra log-message.

[iSOLveIT]

Hi @arwedus, I have been working on the issue you are encountering but unfortunately, I am getting the ff. error message instead: ../sphinx-needs/docs/directives/need.rst:10: WARNING: Inline interpreted text or phrase reference start-string without end-string..

Here is the RST code:

.. req:: User needs to login
   :id: ID123
   :status: open
   :tags: user;login
   :collapse: false

   Our users needs to get logged in via our login forms on **/login.php**.

   - Mode 1: Normal Operation
   - Mode 2 (Special Conditions):
     Mode 2 = In case UTC is not available due to any reason or there is leap second

   Note:

   - See :need:`VA_001` for Mode 1.
   - See :need:`VA_002` for Mode 2.

I am using python==3.10, sphinx==5.2.2, and sphinx-needs==1.2.2. Please provide some information about the version of Python, Sphinx, and Sphinx-Needs you use. Also, I could able to help best if you could provide an example project which I could use to reproduce the warning you are getting. Thank you very much.