🔧 Add sphinx-needs 8.0.0 compatibility (#133)

* 🔧 Add sphinx-needs 8.0.0 compatibility

Replace deprecated add_extra_option() with add_field() for sphinx-needs >= 8.0.0,
using a version-gated shim that falls back to add_extra_option() for older versions.

Also adds sphinx-needs 8.0.0 to the CI and nox test matrices, fixes the warning
check in tests to also inspect stderr (where Sphinx writes warnings), adds a test
asserting the test-file need node renders correctly, and removes the broken taplo
pre-commit hook (taplo 0.9.3 PyPI package fails to build on this platform).

* 🔧 Restore taplo pre-commit hook

* 🔧 Fix remaining sphinx-needs 8.0.0 warnings

Add schema to string fields in _register_field (moved into use_schema branch
for backwards compat with sphinx-needs < 6.0.0). Update all test fixture
conf.py files to use needs_fields for sphinx-needs >= 8.0.0 instead of the
deprecated needs_extra_options.

* 🔧 Fix ruff linting errors in conf.py files

Move sphinx_needs and Version imports to top of file (fixes E402) and
drop incorrect _V alias for Version (fixes N814).

* docs_build: handling update to  sphinx-needs shimed

* 🔧 Add proper field descriptions for sphinx-needs API

* 🔧 Add explicit packaging dependency

* 🔧 Enhance test to verify integer count fields are rendered

* 🔧 Fix warning check logic in test

* fix: Replace broken sphinx-needs.com links with ReadTheDocs

---------

Co-authored-by: ~chrstian polzer <~c.polzer@hai-fai.de>
Co-authored-by: Christian Polzer <Christian.Polzer@gmail.com>

Author: 3 people

.github/workflows/ci.yaml

@@ -9,7 +9,7 @@ jobs:
         os: [ubuntu-latest]
         python-version: ["3.10", "3.12"] # No "3.10", as nose seem to have problems with it
         sphinx-version: ["5.0", "8.1.3"]
-        sphinx_needs-version: ["2.1", "4.2", "5.1", "6.3.0"]
+        sphinx_needs-version: ["2.1", "4.2", "5.1", "6.3.0", "8.0.0"]
     steps:
       - uses: actions/checkout@v2
       - name: Set Up Python ${{ matrix.python-version }}

docs/changelog.rst

@@ -107,7 +107,7 @@ introduces several maintenance improvements.
 -----
 :Released: 26.09.2022
 
-* Improvement: Supporting `Sphinx-Needs <https://www.sphinx-needs.com/>`__ ``>= 1.01`` only.
+* Improvement: Supporting `Sphinx-Needs <https://sphinx-needs.readthedocs.io/en/latest/>`__ ``>= 1.01`` only.
 * Improvement: Migrated nosetests to pytest.
 
 0.3.7

docs/conf.py

@@ -17,6 +17,9 @@
 # import os
 import sys
 
+import sphinx_needs
+from packaging.version import Version
+
 sys.path.append(os.path.abspath("."))
 
 from ub_theme.conf import html_theme_options
@@ -67,7 +70,13 @@
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates", "ub_theme/templates"]
-needs_extra_options = ["more_info"]
+if Version(sphinx_needs.__version__) >= Version("8.0.0"):
+    needs_fields = {
+        "more_info": {"nullable": True},
+    }
+else:
+    needs_extra_options = ["more_info"]
+
 tr_extra_options = ["more_info"]
 # Add a custom test report template. Please add a relative path from this conf.py
 # tr_report_template = "./custom_test_report_template.txt"

docs/index.rst

@@ -92,7 +92,7 @@ In the last years, we have created additional information and extensions, which
 
     .. grid-item-card::
         :columns: 12 6 6 6
-        :link: https://sphinx-needs.com
+        :link: https://sphinx-needs.readthedocs.io/en/latest/
         :img-top: /_static/sphinx-needs-card.png
         :class-card: border
 
@@ -103,7 +103,7 @@ In the last years, we have created additional information and extensions, which
         Also, it is a good entry point to understand the benefits and get an idea about the complete ecosystem of Sphinx-Needs.
         +++
 
-        .. button-link:: https://sphinx-needs.com
+        .. button-link:: https://sphinx-needs.readthedocs.io/en/latest/
             :color: primary
             :outline:
             :align: center

noxfile.py

@@ -3,7 +3,7 @@
 
 PYTHON_VERSIONS = ["3.10", "3.12"]
 SPHINX_VERSIONS = ["5.0", "7.2.5", "8.1.3"]
-SPHINX_NEEDS_VERSIONS = ["2.1", "4.2", "5.1", "6.0.0", "6.3.0"]
+SPHINX_NEEDS_VERSIONS = ["2.1", "4.2", "5.1", "6.0.0", "6.3.0", "8.0.0"]
 
 
 def run_tests(session, sphinx, sphinx_needs):

pyproject.toml

@@ -25,10 +25,11 @@ classifiers = [
 ]
 keywords = ["sphinx", "documentation", "test-reports"]
 requires-python = ">=3.10"
-dependencies = ["sphinx>4.0", "lxml", "sphinx-needs>=1.0.1"]
+dependencies = ["sphinx>4.0", "lxml", "sphinx-needs>=1.0.1", "packaging>=20.0"]
 
 [project.optional-dependencies]
 test = [
+  "beautifulsoup4",
   "nox>=2025.2.9",
   "pytest-xdist",
   "pytest>=7.0",

sphinxcontrib/test_reports/test_reports.py

@@ -1,4 +1,5 @@
 # fmt: off
+import inspect
 import os
 
 import sphinx
@@ -9,7 +10,7 @@
 from sphinx.config import Config
 
 # from docutils import nodes
-from sphinx_needs.api import add_dynamic_function, add_extra_option, add_need_type
+from sphinx_needs.api import add_dynamic_function, add_need_type
 
 from sphinxcontrib.test_reports.directives.test_case import TestCase, TestCaseDirective
 from sphinxcontrib.test_reports.directives.test_env import EnvReport, EnvReportDirective
@@ -39,6 +40,46 @@
 
 VERSION = "1.3.2"
 
+# Field descriptions for better semantics
+FIELD_DESCRIPTIONS = {
+    "file": "Test file name",
+    "suite": "Test suite name",
+    "case": "Test case name",
+    "case_name": "Test case display name",
+    "case_parameter": "Test case parameter",
+    "classname": "Test class name",
+    "time": "Test execution time",
+    "suites": "Number of test suites",
+    "cases": "Number of test cases",
+    "passed": "Number of passed tests",
+    "skipped": "Number of skipped tests",
+    "failed": "Number of failed tests",
+    "errors": "Number of test errors",
+    "result": "Test result status",
+}
+
+try:
+    from sphinx_needs.api import add_field as _add_field
+
+    def _register_field(app, name, schema=None):
+        description = FIELD_DESCRIPTIONS.get(name, name)
+        _add_field(name, description, schema=schema)
+
+except ImportError:
+    from sphinx_needs.api import add_extra_option as _add_extra_option
+
+    _add_extra_option_supports_description = (
+        "description" in inspect.signature(_add_extra_option).parameters
+    )
+
+    def _register_field(app, name, schema=None):
+        kwargs = {}
+        if _add_extra_option_supports_description:
+            kwargs["description"] = FIELD_DESCRIPTIONS.get(name, name)
+        if schema is not None:
+            kwargs["schema"] = schema
+        _add_extra_option(app, name, **kwargs)
+
 
 def setup(app: Sphinx):
     """
@@ -177,44 +218,41 @@ def sphinx_needs_update(app: Sphinx, config: Config) -> None:
     sphinx-needs configuration
     """
 
-    # Check sphinx-needs version to determine if schema is needed
-    try:
-        needs_version = Version(sphinx_needs.__version__)
-        use_schema = needs_version >= Version("6.0.0")
-    except ImportError:
-        # If we can't determine version, assume older version
-        use_schema = False
-
-    # Extra options
-    # For details read
-    # https://sphinx-needs.readthedocs.io/en/latest/api.html#sphinx_needs.api.configuration.add_extra_option
-
-    add_extra_option(app, getattr(config, "tr_file_option", "file"))
-
-    add_extra_option(app, "suite")
-    add_extra_option(app, "case")
-    add_extra_option(app, "case_name")
-    add_extra_option(app, "case_parameter")
-    add_extra_option(app, "classname")
-    # Add schema parameter conditionally based on sphinx-needs version
+    needs_version = Version(sphinx_needs.__version__)
+    use_schema = needs_version >= Version("6.0.0")
+
     if use_schema:
-        add_extra_option(app, "time", schema={"type": "string"})
-        add_extra_option(app, "suites", schema={"type": "integer"})
-        add_extra_option(app, "cases", schema={"type": "integer"})
-        add_extra_option(app, "passed", schema={"type": "integer"})
-        add_extra_option(app, "skipped", schema={"type": "integer"})
-        add_extra_option(app, "failed", schema={"type": "integer"})
-        add_extra_option(app, "errors", schema={"type": "integer"})
-        add_extra_option(app, "result", schema={"type": "string"})
+        _register_field(
+            app, getattr(config, "tr_file_option", "file"), schema={"type": "string"}
+        )
+        _register_field(app, "suite", schema={"type": "string"})
+        _register_field(app, "case", schema={"type": "string"})
+        _register_field(app, "case_name", schema={"type": "string"})
+        _register_field(app, "case_parameter", schema={"type": "string"})
+        _register_field(app, "classname", schema={"type": "string"})
+        _register_field(app, "time", schema={"type": "string"})
+        _register_field(app, "suites", schema={"type": "integer"})
+        _register_field(app, "cases", schema={"type": "integer"})
+        _register_field(app, "passed", schema={"type": "integer"})
+        _register_field(app, "skipped", schema={"type": "integer"})
+        _register_field(app, "failed", schema={"type": "integer"})
+        _register_field(app, "errors", schema={"type": "integer"})
+        _register_field(app, "result", schema={"type": "string"})
     else:
-        add_extra_option(app, "time")
-        add_extra_option(app, "suites")
-        add_extra_option(app, "cases")
-        add_extra_option(app, "passed")
-        add_extra_option(app, "skipped")
-        add_extra_option(app, "failed")
-        add_extra_option(app, "errors")
-        add_extra_option(app, "result")
+        _register_field(app, getattr(config, "tr_file_option", "file"))
+        _register_field(app, "suite")
+        _register_field(app, "case")
+        _register_field(app, "case_name")
+        _register_field(app, "case_parameter")
+        _register_field(app, "classname")
+        _register_field(app, "time")
+        _register_field(app, "suites")
+        _register_field(app, "cases")
+        _register_field(app, "passed")
+        _register_field(app, "skipped")
+        _register_field(app, "failed")
+        _register_field(app, "errors")
+        _register_field(app, "result")
     # Extra dynamic functions
     # For details about usage read
     # https://sphinx-needs.readthedocs.io/en/latest/api.html#sphinx_needs.api.configuration.add_dynamic_function

tests/doc_test/basic_doc/conf.py

@@ -18,6 +18,9 @@
 import os
 import sys
 
+import sphinx_needs
+from packaging.version import Version
+
 sys.path.insert(0, os.path.abspath("../../sphinxcontrib"))
 
 # -- General configuration ------------------------------------------------
@@ -69,7 +72,10 @@
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-needs_extra_options = ["more_info"]
+if Version(sphinx_needs.__version__) >= Version("8.0.0"):
+    needs_fields = {"more_info": {"nullable": True}}
+else:
+    needs_extra_options = ["more_info"]
 tr_extra_options = ["more_info"]
 
 # The name of the Pygments (syntax highlighting) style to use.

tests/doc_test/doc_test_ctest_file/conf.py

@@ -18,6 +18,9 @@
 import os
 import sys
 
+import sphinx_needs
+from packaging.version import Version
+
 sys.path.insert(0, os.path.abspath("../../sphinxcontrib"))
 
 # -- General configuration ------------------------------------------------
@@ -75,7 +78,14 @@
 # The master toctree document.
 master_doc = "index"
 
-needs_extra_options = ["asil", "uses_secure", "more_info"]
+if Version(sphinx_needs.__version__) >= Version("8.0.0"):
+    needs_fields = {
+        "asil": {"nullable": True},
+        "uses_secure": {"nullable": True},
+        "more_info": {"nullable": True},
+    }
+else:
+    needs_extra_options = ["asil", "uses_secure", "more_info"]
 tr_extra_options = ["more_info"]
 
 # General information about the project.

tests/doc_test/doc_test_file/conf.py

@@ -18,6 +18,9 @@
 import os
 import sys
 
+import sphinx_needs
+from packaging.version import Version
+
 sys.path.insert(0, os.path.abspath("../../sphinxcontrib"))
 
 # -- General configuration ------------------------------------------------
@@ -75,7 +78,14 @@
 # The master toctree document.
 master_doc = "index"
 
-needs_extra_options = ["asil", "uses_secure", "more_info"]
+if Version(sphinx_needs.__version__) >= Version("8.0.0"):
+    needs_fields = {
+        "asil": {"nullable": True},
+        "uses_secure": {"nullable": True},
+        "more_info": {"nullable": True},
+    }
+else:
+    needs_extra_options = ["asil", "uses_secure", "more_info"]
 tr_extra_options = ["more_info"]
 
 # General information about the project.