diff --git a/sphinx_needs/layout.py b/sphinx_needs/layout.py index 1df7773a..ad2a49b4 100644 --- a/sphinx_needs/layout.py +++ b/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( '<>' '<>' # 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: ``<>``, + + :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" diff --git a/tests/conftest.py b/tests/conftest.py index e39cd852..9317a88b 100644 --- a/tests/conftest.py +++ b/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 diff --git a/tests/doc_test/doc_layout/_images/smile.png b/tests/doc_test/doc_layout/_images/smile.png new file mode 100644 index 00000000..46371191 Binary files /dev/null and b/tests/doc_test/doc_layout/_images/smile.png differ diff --git a/tests/doc_test/doc_layout/conf.py b/tests/doc_test/doc_layout/conf.py index c118c581..fe0dbc11 100644 --- a/tests/doc_test/doc_layout/conf.py +++ b/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**: <>', '**author**: <>', + '**author_image**: <>', ], - "side": ['<>'], + "side": ['<>'], + }, + }, + "image_author": { + "grid": "simple_side_right_partial", + "layout": { + "head": ['**<>**'], + "meta": [ + '**status**: <>', + r'<>', + r'<>', + ], + "side": ['<>'], }, }, "optional_author": { diff --git a/tests/doc_test/doc_layout/index.rst b/tests/doc_test/doc_layout/index.rst index ce1cf38e..b4a3d9bf 100644 --- a/tests/doc_test/doc_layout/index.rst +++ b/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 + diff --git a/tests/doc_test/doc_layout/subfolder_1/index.rst b/tests/doc_test/doc_layout/subfolder_1/index.rst new file mode 100644 index 00000000..42546760 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/doc_test/doc_layout/subfolder_2/index.rst b/tests/doc_test/doc_layout/subfolder_2/index.rst new file mode 100644 index 00000000..4970aedf --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/doc_test/doc_layout/subfolder_2/subfolder_smile.png b/tests/doc_test/doc_layout/subfolder_2/subfolder_smile.png new file mode 100644 index 00000000..46371191 Binary files /dev/null and b/tests/doc_test/doc_layout/subfolder_2/subfolder_smile.png differ diff --git a/tests/test_layouts.py b/tests/test_layouts.py index bed530dc..14abb11b 100644 --- a/tests/test_layouts.py +++ b/tests/test_layouts.py @@ -5,12 +5,15 @@ @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 @@ -18,7 +21,7 @@ def test_doc_build_html(test_app): assert "title_example_layout" in html needs = extract_needs_from_html(html) - assert len(needs) == 6 + assert len(needs) == 7 assert ( 'author: some author' @@ -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 ( + '_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 ( + '../_images/smile.png' + in html_subfolder_1 + ) + assert '_images/smile.png' 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 ( + '../_images/subfolder_smile.png' + in html_subfolder_2 + ) + assert ( + 'subfolder_2/subfolder_smile.png' + in html_subfolder_2 + )