🐛 FIX: Image layout function (#1135)

Removes the relative path calculation from the "image" function in
layout.py,as it was broken.
Now all set url-paths must be relative to the documentation root.

sphinx_needs/layout.py

@@ -844,7 +844,7 @@ def image(
         """
         See https://docutils.sourceforge.io/docs/ref/rst/directives.html#images
 
-        If url starts with ``icon:`` the following string is taken is icon-name and the related icon is shown.
+        If **url** starts with ``icon:`` the following string is taken as icon-name and the related icon is shown.
         Example: ``icon:activity`` will show:
 
         .. image:: _static/activity.png
@@ -857,7 +857,17 @@ def image(
             '<<image("icon:bell", height="20px", align="center")>>'
             '<<image("field:url", height="60px", align="center")>>'  # Get url from need['url']
 
-        :param url:
+        If **url** starts with ``:field`` the URL value is taken from the defined field of the current need
+        object.
+
+        .. hint:: Relative URLs
+
+           If a relative path for the URL parameter is given, it must be relative to the documentation
+           root folder and not relative to the current need location, for which it gets executed.
+
+           Example: ``<<image("_static/picture.png")>>``,
+
+        :param url: Relative path to the project folder or an absolute path
         :param height:
         :param width:
         :param align:
@@ -927,14 +937,6 @@ def image(
 
             url = value
 
-            if (
-                not is_external
-                and not os.path.isabs(url)
-                and (docname := self.need["docname"])
-            ):
-                subfolder_amount = docname.count("/")
-                url = "../" * subfolder_amount + url
-
         if is_external:
             url_parsed = urlparse(url)
             filename = os.path.basename(url_parsed.path) + ".png"

tests/conftest.py

@@ -18,6 +18,7 @@
 from sphinx.application import Sphinx
 from sphinx.testing.path import path
 from sphinx.testing.util import SphinxTestApp
+from sphinx.util.console import strip_colors
 from syrupy.extensions.single_file import SingleFileSnapshotExtension, WriteMode
 from xprocess import ProcessStarter
 
@@ -283,6 +284,16 @@ def test_app(make_app, sphinx_test_tempdir, request):
         docutilsconf=builder_params.get("docutilsconf"),
         parallel=builder_params.get("parallel", 0),
     )
+    # Add the Sphinx warning as list to the app
+    # Somehow "app._warning" seems to be just a boolean, if the builder is "latex" or "singlehtml".
+    # In this case we don't catch the warnings.
+    if builder_params.get("buildername", "html") == "html":
+        app.warning_list = strip_colors(
+            app._warning.getvalue().replace(str(app.srcdir), "srcdir")
+        ).splitlines()
+    else:
+        app.warning_list = None
+
     # Add the spec_pattern as an attribute to the Sphinx app object
     app.spec_pattern = builder_params.get("spec_pattern", "*.cy.js")
     # Add the ``test_js`` function as an attribute to the Sphinx app object

tests/doc_test/doc_layout/conf.py

@@ -31,7 +31,7 @@
     },
 ]
 
-needs_extra_options = ["author"]
+needs_extra_options = ["author", "author_image"]
 
 needs_layouts = {
     "example": {
@@ -41,8 +41,21 @@
             "meta": [
                 '**status**: <<meta("status")>>',
                 '**author**: <<meta("author")>>',
+                '**author_image**: <<meta("author_image")>>',
             ],
-            "side": ['<<image("_images/{{author}}.png", align="center")>>'],
+            "side": ['<<image("_images/smile.png", align="center")>>'],
+        },
+    },
+    "image_author": {
+        "grid": "simple_side_right_partial",
+        "layout": {
+            "head": ['**<<meta("title")>>**'],
+            "meta": [
+                '**status**: <<meta("status")>>',
+                r'<<meta("author", prefix="\*\*author\*\*: ")>>',
+                r'<<meta("author_image", prefix="\*\*author_image\*\*: ")>>',
+            ],
+            "side": ['<<image("field:author_image", align="center")>>'],
         },
     },
     "optional_author": {

tests/doc_test/doc_layout/index.rst

@@ -1,6 +1,11 @@
 TEST DOCUMENT
 =============
 
+.. toctree::
+
+   subfolder_1/index
+   subfolder_2/index
+
 .. spec:: title_clean_layout
    :layout: clean
 
@@ -12,10 +17,17 @@ TEST DOCUMENT
 
 .. spec:: title_example_layout
    :layout: example
+   :author: some author
 
 .. spec:: title_layout_optional_author
    :layout: optional_author
    :author: some author
 
+.. spec:: title_layout_image_author
+   :layout: image_author
+   :author: some author
+   :author_image: _images/smile.png
+
 .. spec:: title_layout_footer_grid
    :layout: footer_grid
+

tests/doc_test/doc_layout/subfolder_1/index.rst

@@ -0,0 +1,8 @@
+Subfolder 1
+===========
+
+Image-layout test
+
+.. spec:: title_layout_image_author_sub_1
+   :layout: image_author
+   :author_image: _images/smile.png

tests/doc_test/doc_layout/subfolder_2/index.rst

@@ -0,0 +1,8 @@
+Subfolder 2
+===========
+
+Image-layout test with local image file
+
+.. spec:: title_layout_image_author_sub_2
+   :layout: image_author
+   :author_image: subfolder_2/subfolder_smile.png

tests/test_layouts.py

@@ -5,20 +5,23 @@
 
 @pytest.mark.parametrize(
     "test_app",
-    [{"buildername": "html", "srcdir": "doc_test/doc_layout"}],
+    [{"buildername": "html", "srcdir": "doc_test/doc_layout", "no_plantuml": True}],
     indirect=True,
 )
 def test_doc_build_html(test_app):
     app = test_app
     app.build()
+
+    assert len(app.warning_list) == 0
+
     html = (app.outdir / "index.html").read_text()
     assert "title_clean_layout" in html
     assert "title_complete_layout" in html
     assert "title_focus_layout" not in html
     assert "title_example_layout" in html
 
     needs = extract_needs_from_html(html)
-    assert len(needs) == 6
+    assert len(needs) == 7
 
     assert (
         '<span class="needs_label"><strong>author</strong>: </span><span class="needs_data">some author</span>'
@@ -28,3 +31,28 @@ def test_doc_build_html(test_app):
 
     # check simple_footer grid layout
     assert "custom footer for" in html
+
+    # Check image is correctly referenced
+    assert (
+        '<img alt="_images/smile.png" class="needs_image align-center" src="_images/smile.png" />'
+        in html
+    )
+
+    # Check a "root"-image is correctly referenced in subfolders
+    html_subfolder_1 = (app.outdir / "subfolder_1/index.html").read_text()
+    assert (
+        '<img alt="../_images/smile.png" class="needs_image align-center" src="../_images/smile.png" />'
+        in html_subfolder_1
+    )
+    assert '<span class="needs_data">_images/smile.png</span>' in html_subfolder_1
+
+    # Check a "subfolder"-image is correctly referenced in subfolders
+    html_subfolder_2 = (app.outdir / "subfolder_2/index.html").read_text()
+    assert (
+        '<img alt="../_images/subfolder_smile.png" class="needs_image align-center" src="../_images/subfolder_smile.png" />'
+        in html_subfolder_2
+    )
+    assert (
+        '<span class="needs_data">subfolder_2/subfolder_smile.png</span>'
+        in html_subfolder_2
+    )