doc: Doc nice deprecated tests (#945)

---------
Co-authored-by: vitthalmagadum <vitthal.magadum-ext@arista.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

anta/decorators.py

@@ -63,13 +63,15 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
     return decorator
 
 
-def deprecated_test_class(new_tests: list[str] | None = None) -> Callable[[type[AntaTest]], type[AntaTest]]:
+def deprecated_test_class(new_tests: list[str] | None = None, removal_in_version: str | None = None) -> Callable[[type[AntaTest]], type[AntaTest]]:
     """Return a decorator to log a message of WARNING severity when a test is deprecated.
 
     Parameters
     ----------
     new_tests
         A list of new test classes that should replace the deprecated test.
+    removal_in_version
+        A string indicating the version in which the test will be removed.
 
     Returns
     -------
@@ -102,6 +104,9 @@ def new_init(*args: Any, **kwargs: Any) -> None:
                 logger.warning("%s test is deprecated.", cls.name)
             orig_init(*args, **kwargs)
 
+        if removal_in_version is not None:
+            cls.__removal_in_version = removal_in_version
+
         # NOTE: we are ignoring mypy warning as we want to assign to a method here
         cls.__init__ = new_init  # type: ignore[method-assign]
         return cls

anta/models.py

@@ -328,6 +328,8 @@ def test(self) -> None:
     # Optional class attributes
     name: ClassVar[str]
     description: ClassVar[str]
+    __removal_in_version: ClassVar[str]
+    """Internal class variable set by the `deprecated_test_class` decorator."""
 
     # Mandatory class attributes
     # TODO: find a way to tell mypy these are mandatory for child classes

anta/tests/stun.py

@@ -91,15 +91,13 @@ def test(self) -> None:
                 self.result.is_failure(f"{client_input} - Incorrect public-facing port - Expected: {input_public_port} Actual: {actual_public_port}")
 
 
-@deprecated_test_class(new_tests=["VerifyStunClientTranslation"])
+@deprecated_test_class(new_tests=["VerifyStunClientTranslation"], removal_in_version="v2.0.0")
 class VerifyStunClient(VerifyStunClientTranslation):
     """(Deprecated) Verifies the translation for a source address on a STUN client.
 
     Alias for the VerifyStunClientTranslation test to maintain backward compatibility.
     When initialized, it will emit a deprecation warning and call the VerifyStunClientTranslation test.
 
-    TODO: Remove this class in ANTA v2.0.0.
-
     Examples
     --------
     ```yaml
@@ -113,6 +111,8 @@ class VerifyStunClient(VerifyStunClientTranslation):
     ```
     """
 
+    # TODO: Remove this class in ANTA v2.0.0.
+
     # required to redefine name an description to overwrite parent class.
     name = "VerifyStunClient"
     description = "(Deprecated) Verifies the translation for a source address on a STUN client."

docs/templates/python/material/class.html.jinja

@@ -53,3 +53,21 @@
   {{ super() }}
 {%   endif %}
 {% endblock source %}
+
+{# overwrite block base to render some stuff on deprecation for anta_test #}
+{% block bases %}
+{{ super() }}
+
+{% for dec in class.decorators %}
+{% if dec.value.function.name == "deprecated_test_class" %}
+<img alt="Static Badge" src="https://img.shields.io/badge/DEPRECATED-yellow?style=flat&logoSize=auto">
+{% for arg in dec.value.arguments | selectattr("name", "equalto", "removal_in_version") | list %}
+<img alt="Static Badge" src="https://img.shields.io/badge/REMOVAL-{{ arg.value[1:-1] }}-grey?style=flat&logoSize=auto&labelColor=red">
+{% endfor %}
+<br/>
+{% for arg in dec.value.arguments | selectattr("name", "equalto", "new_tests") | list %}
+<strong>Replaced with:</strong> {{ arg.value.elements | map("replace", "'", "<code>", 1) | map("replace", "'", "</code>", 1) | join(", ") | safe }}
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endblock bases %}