doc: Make AntaTest documentation Great Again (#514)

Co-authored-by: Carl Baillargeon <[email protected]>

anta/decorators.py

@@ -24,7 +24,7 @@ def deprecated_test(new_tests: list[str] | None = None) -> Callable[[F], F]:
     ----
         new_tests (Optional[list[str]]): A list of new test classes that should replace the deprecated test.
 
-    Returns:
+    Returns
     -------
         Callable[[F], F]: A decorator that can be used to wrap test functions.
 
@@ -37,7 +37,7 @@ def decorator(function: F) -> F:
         ----
             function (F): The test function to be decorated.
 
-        Returns:
+        Returns
         -------
             F: The decorated function.
 
@@ -68,7 +68,7 @@ def skip_on_platforms(platforms: list[str]) -> Callable[[F], F]:
     ----
         platforms (list[str]): List of hardware models on which the test should be skipped.
 
-    Returns:
+    Returns
     -------
         Callable[[F], F]: A decorator that can be used to wrap test functions.
 
@@ -81,7 +81,7 @@ def decorator(function: F) -> F:
         ----
             function (F): The test function to be decorated.
 
-        Returns:
+        Returns
         -------
             F: The decorated function.
 

anta/inventory/__init__.py

@@ -98,7 +98,7 @@ def _parse_networks(
             inventory (AntaInventory): AntaInventory to add the parsed devices to
             **kwargs (dict[str, Any]): Additional keywork arguments to pass to the device constructor
 
-        Raises:
+        Raises
         ------
             InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema.
 
@@ -131,7 +131,7 @@ def _parse_ranges(
             inventory (AntaInventory): AntaInventory to add the parsed devices to
             **kwargs (dict[str, Any]): Additional keywork arguments to pass to the device constructor
 
-        Raises:
+        Raises
         ------
             InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema.
 
@@ -187,7 +187,7 @@ def parse(
             insecure (bool): Disable SSH Host Key validation
             disable_cache (bool): Disable cache globally
 
-        Raises:
+        Raises
         ------
             InventoryRootKeyError: Root key of inventory is missing.
             InventoryIncorrectSchemaError: Inventory file is not following AntaInventory Schema.
@@ -255,7 +255,7 @@ def get_inventory(self, *, established_only: bool = False, tags: list[str] | Non
             established_only: Whether or not to include only established devices. Default False.
             tags: List of tags to filter devices.
 
-        Returns:
+        Returns
         -------
             AntaInventory: An inventory with filtered AntaDevice objects.
 

anta/models.py

@@ -80,7 +80,7 @@ def render(self, **params: dict[str, Any]) -> AntaCommand:
         ----
             params: dictionary of variables with string values to render the Python f-string
 
-        Returns:
+        Returns
         -------
             command: The rendered AntaCommand.
                      This AntaCommand instance have a template attribute that references this
@@ -494,7 +494,7 @@ async def wrapper(
                           This list must have the same length and order than the `instance_commands` instance attribute.
                 kwargs: Any keyword argument to pass to the test.
 
-            Returns:
+            Returns
             -------
                 result: TestResult instance attribute populated with error status if any
 

anta/reporter/__init__.py

@@ -34,7 +34,7 @@ def _split_list_to_txt_list(self, usr_list: list[str], delimiter: str | None = N
             usr_list (list[str]): List of string to concatenate
             delimiter (str, optional): A delimiter to use to start string. Defaults to None.
 
-        Returns:
+        Returns
         -------
             str: Multi-lines string
 
@@ -53,7 +53,7 @@ def _build_headers(self, headers: list[str], table: Table) -> Table:
             headers (list[str]): List of headers
             table (Table): A rich Table instance
 
-        Returns:
+        Returns
         -------
             Table: A rich Table instance with headers
 
@@ -75,7 +75,7 @@ def _color_result(self, status: TestStatus) -> str:
         ----
             status (TestStatus): status value to color
 
-        Returns:
+        Returns
         -------
         str: the colored string
 
@@ -101,7 +101,7 @@ def report_all(
             testcase (str, optional): A test name to search for. Defaults to None.
             title (str, optional): Title for the report. Defaults to 'All tests results'.
 
-        Returns:
+        Returns
         -------
             Table: A fully populated rich Table
 
@@ -135,7 +135,7 @@ def report_summary_tests(
             testcase (str, optional): A test name to search for. Defaults to None.
             title (str, optional): Title for the report. Defaults to 'All tests results'.
 
-        Returns:
+        Returns
         -------
             Table: A fully populated rich Table
 
@@ -185,7 +185,7 @@ def report_summary_hosts(
             host (str, optional): IP Address of a host to search for. Defaults to None.
             title (str, optional): Title for the report. Defaults to 'All tests results'.
 
-        Returns:
+        Returns
         -------
             Table: A fully populated rich Table
 
@@ -257,7 +257,7 @@ def render(self, data: list[dict[str, Any]], *, trim_blocks: bool = True, lstrip
             trim_blocks (bool, optional): enable trim_blocks for J2 rendering. Defaults to True.
             lstrip_blocks (bool, optional): enable lstrip_blocks for J2 rendering. Defaults to True.
 
-        Returns:
+        Returns
         -------
             str: rendered template
 

anta/result_manager/__init__.py

@@ -164,7 +164,7 @@ def get_result_by_test(self, test_name: str) -> list[TestResult]:
         ----
             test_name (str): Test name to use to filter results
 
-        Returns:
+        Returns
         -------
             list[TestResult]: List of results related to the test.
 
@@ -178,7 +178,7 @@ def get_result_by_host(self, host_ip: str) -> list[TestResult]:
         ----
             host_ip (str): IP Address of the host to use to filter results.
 
-        Returns:
+        Returns
         -------
             list[TestResult]: List of results related to the host.
 

anta/runner.py

@@ -32,7 +32,7 @@ def log_cache_statistics(devices: list[AntaDevice]) -> None:
     ----
         devices: List of devices in the inventory.
 
-    Returns:
+    Returns
     -------
         None: Log the cache statistics for each device in the inventory.
 
@@ -62,7 +62,7 @@ async def main(manager: ResultManager, inventory: AntaInventory, catalog: AntaCa
         tags: List of tags to filter devices from the inventory. Defaults to None.
         established_only: Include only established device(s). Defaults to True.
 
-    Returns:
+    Returns
     -------
         any: ResultManager object gets updated with the test results.
 

anta/tests/aaa.py

@@ -20,9 +20,19 @@
 class VerifyTacacsSourceIntf(AntaTest):
     """Verifies TACACS source-interface for a specified VRF.
 
-    Expected Results:
-        * Success: The test will pass if the provided TACACS source-interface is configured in the specified VRF.
-        * Failure: The test will fail if the provided TACACS source-interface is NOT configured in the specified VRF.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided TACACS source-interface is configured in the specified VRF.
+    * Failure: The test will fail if the provided TACACS source-interface is NOT configured in the specified VRF.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyTacacsSourceIntf:
+          intf: Management0
+          vrf: MGMT
+    ```
     """
 
     name = "VerifyTacacsSourceIntf"
@@ -54,9 +64,21 @@ def test(self) -> None:
 class VerifyTacacsServers(AntaTest):
     """Verifies TACACS servers are configured for a specified VRF.
 
-    Expected Results:
-        * Success: The test will pass if the provided TACACS servers are configured in the specified VRF.
-        * Failure: The test will fail if the provided TACACS servers are NOT configured in the specified VRF.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided TACACS servers are configured in the specified VRF.
+    * Failure: The test will fail if the provided TACACS servers are NOT configured in the specified VRF.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyTacacsServers:
+          servers:
+            - 10.10.10.21
+            - 10.10.10.22
+          vrf: MGMT
+    ```
     """
 
     name = "VerifyTacacsServers"
@@ -96,9 +118,20 @@ def test(self) -> None:
 class VerifyTacacsServerGroups(AntaTest):
     """Verifies if the provided TACACS server group(s) are configured.
 
-    Expected Results:
-        * Success: The test will pass if the provided TACACS server group(s) are configured.
-        * Failure: The test will fail if one or all the provided TACACS server group(s) are NOT configured.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided TACACS server group(s) are configured.
+    * Failure: The test will fail if one or all the provided TACACS server group(s) are NOT configured.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyTacacsServerGroups:
+          groups:
+            - TACACS-GROUP1
+            - TACACS-GROUP2
+    ```
     """
 
     name = "VerifyTacacsServerGroups"
@@ -130,9 +163,25 @@ def test(self) -> None:
 class VerifyAuthenMethods(AntaTest):
     """Verifies the AAA authentication method lists for different authentication types (login, enable, dot1x).
 
-    Expected Results:
-        * Success: The test will pass if the provided AAA authentication method list is matching in the configured authentication types.
-        * Failure: The test will fail if the provided AAA authentication method list is NOT matching in the configured authentication types.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided AAA authentication method list is matching in the configured authentication types.
+    * Failure: The test will fail if the provided AAA authentication method list is NOT matching in the configured authentication types.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyAuthenMethods:
+        methods:
+          - local
+          - none
+          - logging
+        types:
+          - login
+          - enable
+          - dot1x
+    ```
     """
 
     name = "VerifyAuthenMethods"
@@ -176,9 +225,24 @@ def test(self) -> None:
 class VerifyAuthzMethods(AntaTest):
     """Verifies the AAA authorization method lists for different authorization types (commands, exec).
 
-    Expected Results:
-        * Success: The test will pass if the provided AAA authorization method list is matching in the configured authorization types.
-        * Failure: The test will fail if the provided AAA authorization method list is NOT matching in the configured authorization types.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided AAA authorization method list is matching in the configured authorization types.
+    * Failure: The test will fail if the provided AAA authorization method list is NOT matching in the configured authorization types.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyAuthzMethods:
+          methods:
+            - local
+            - none
+            - logging
+          types:
+            - commands
+            - exec
+    ```
     """
 
     name = "VerifyAuthzMethods"
@@ -215,9 +279,26 @@ def test(self) -> None:
 class VerifyAcctDefaultMethods(AntaTest):
     """Verifies the AAA accounting default method lists for different accounting types (system, exec, commands, dot1x).
 
-    Expected Results:
-        * Success: The test will pass if the provided AAA accounting default method list is matching in the configured accounting types.
-        * Failure: The test will fail if the provided AAA accounting default method list is NOT matching in the configured accounting types.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided AAA accounting default method list is matching in the configured accounting types.
+    * Failure: The test will fail if the provided AAA accounting default method list is NOT matching in the configured accounting types.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyAcctDefaultMethods:
+          methods:
+            - local
+            - none
+            - logging
+          types:
+            - system
+            - exec
+            - commands
+            - dot1x
+    ```
     """
 
     name = "VerifyAcctDefaultMethods"
@@ -261,9 +342,26 @@ def test(self) -> None:
 class VerifyAcctConsoleMethods(AntaTest):
     """Verifies the AAA accounting console method lists for different accounting types (system, exec, commands, dot1x).
 
-    Expected Results:
-        * Success: The test will pass if the provided AAA accounting console method list is matching in the configured accounting types.
-        * Failure: The test will fail if the provided AAA accounting console method list is NOT matching in the configured accounting types.
+    Expected Results
+    ----------------
+    * Success: The test will pass if the provided AAA accounting console method list is matching in the configured accounting types.
+    * Failure: The test will fail if the provided AAA accounting console method list is NOT matching in the configured accounting types.
+
+    Examples
+    --------
+    ```yaml
+    anta.tests.aaa:
+      - VerifyAcctConsoleMethods:
+          methods:
+            - local
+            - none
+            - logging
+          types:
+            - system
+            - exec
+            - commands
+            - dot1x
+    ```
     """
 
     name = "VerifyAcctConsoleMethods"