Fix build failure with newer sphinx dependencies:

[LocutusOfBorg]

=================================== FAILURES =================================== __________________________ test_sd_custom_directives ___________________________

sphinx_builder = <function sphinx_builder.._create_project at 0x73427f5c0900> file_regression = <pytest_regressions.file_regression.FileRegressionFixture object at 0x73427f8ba2c0>

@pytest.mark.skipif(not MYST_INSTALLED, reason="myst-parser not installed")
def test_sd_custom_directives(
    sphinx_builder: Callable[..., SphinxBuilder], file_regression
):
    """Test that the defaults are used."""
    builder = sphinx_builder(
        conf_kwargs={
            "extensions": ["myst_parser", "sphinx_design"],
            "sd_custom_directives": {
                "dropdown-syntax": {
                    "inherit": "dropdown",
                    "argument": "Syntax",
                    "options": {
                        "color": "primary",
                        "icon": "code",
                    },
                }
            },
        }
    )
    content = "# Heading\n\n```{dropdown-syntax}\ncontent\n```"
    builder.src_path.joinpath("index.md").write_text(content, encoding="utf8")
    builder.build()
    doctree = builder.get_doctree("index", post_transforms=False)
    doctree.attributes.pop("translation_progress", None)  # added in sphinx 7.1

  file_regression.check(

        doctree.pformat(),
        basename="sd_custom_directives",
        extension=".xml",
        encoding="utf8",
    )

E AssertionError: FILES DIFFER:
E /tmp/pytest-of-pbuilder/pytest-0/test_sd_custom_directives0/test_snippets/sd_custom_directives.xml
E /tmp/pytest-of-pbuilder/pytest-0/test_sd_custom_directives0/test_snippets/sd_custom_directives.obtained.xml
E HTML DIFF: /tmp/pytest-of-pbuilder/pytest-0/test_sd_custom_directives0/test_snippets/sd_custom_directives.obtained.diff.html
E ---
E +++
E @@ -2,7 +2,7 @@
E

E <title>
E Heading
E -
E +
E
E Syntax
E

tests/test_snippets.py:190: AssertionError
=============================== warnings summary =============================== tests/test_snippets.py::test_sd_hide_title_rst
tests/test_snippets.py::test_sd_hide_title_myst
tests/test_snippets.py::test_sd_custom_directives

[amotl]

Hi Gianfranco,

we discovered the same issue with the test suite on the downstream sphinx-design-elements project, and found docutils 0.22 to be the root cause for the updated rendering of boolean values.

We've resolved it in code, in order to be able to test against multiple versions of docutils without needing to change the test reference snippets. The resources listed below include more information about our thought process.

• Test suite compatibility with docutils 0.22 #249
• Add compatibility with docutils 0.22 tech-writing/sphinx-design-elements#166 (review)

With kind regards,
Andreas.

[amotl]

An alternative is to actually update the snippets like you are proposing, and add a package dependency pinning for docutils>=0.22 without much ado. Do you think this is a viable option, @chrisjsewell? I think it's problematic, because this would mean sphinx-design can no longer work on installations that require previous versions of docutils.

[chrisjsewell]

Fixed in latest release 😄