doc: Make API documentation great again

anta/catalog.py

@@ -39,8 +39,12 @@
 class AntaTestDefinition(BaseModel):
     """Define a test with its associated inputs.
 
-    test: An AntaTest concrete subclass
-    inputs: The associated AntaTest.Input subclass instance
+    Attributes
+    ----------
+    test
+        An AntaTest concrete subclass.
+    inputs
+        The associated AntaTest.Input subclass instance.
     """
 
     model_config = ConfigDict(frozen=True)
@@ -60,6 +64,7 @@ def serialize_model(self) -> dict[str, AntaTest.Input]:
 
         Returns
         -------
+        dict
             A dictionary representing the model.
         """
         return {self.test.__name__: self.inputs}
@@ -132,14 +137,14 @@ def check_inputs(self) -> AntaTestDefinition:
 class AntaCatalogFile(RootModel[dict[ImportString[Any], list[AntaTestDefinition]]]):  # pylint: disable=too-few-public-methods
     """Represents an ANTA Test Catalog File.
 
-    Example:
+    Example
     -------
-        A valid test catalog file must have the following structure:
-        ```
-        <Python module>:
-            - <AntaTest subclass>:
-                <AntaTest.Input compliant dictionary>
-        ```
+    A valid test catalog file must have the following structure:
+    ```
+    <Python module>:
+        - <AntaTest subclass>:
+            <AntaTest.Input compliant dictionary>
+    ```
 
     """
 
@@ -149,16 +154,16 @@ class AntaCatalogFile(RootModel[dict[ImportString[Any], list[AntaTestDefinition]
     def flatten_modules(data: dict[str, Any], package: str | None = None) -> dict[ModuleType, list[Any]]:
         """Allow the user to provide a data structure with nested Python modules.
 
-        Example:
+        Example
         -------
-            ```
-            anta.tests.routing:
-              generic:
-                - <AntaTestDefinition>
-              bgp:
-                - <AntaTestDefinition>
-            ```
-            `anta.tests.routing.generic` and `anta.tests.routing.bgp` are importable Python modules.
+        ```
+        anta.tests.routing:
+          generic:
+            - <AntaTestDefinition>
+          bgp:
+            - <AntaTestDefinition>
+        ```
+        `anta.tests.routing.generic` and `anta.tests.routing.bgp` are importable Python modules.
 
         """
         modules: dict[ModuleType, list[Any]] = {}
@@ -234,6 +239,7 @@ def yaml(self) -> str:
 
         Returns
         -------
+        str
             The YAML representation string of this model.
         """
         # TODO: Pydantic and YAML serialization/deserialization is not supported natively.
@@ -247,6 +253,7 @@ def to_json(self) -> str:
 
         Returns
         -------
+        str
             The JSON representation string of this model.
         """
         return self.model_dump_json(serialize_as_any=True, exclude_unset=True, indent=2)
@@ -267,8 +274,10 @@ def __init__(
 
         Parameters
         ----------
-            tests: A list of AntaTestDefinition instances.
-            filename: The path from which the catalog is loaded.
+        tests
+            A list of AntaTestDefinition instances.
+        filename
+            The path from which the catalog is loaded.
 
         """
         self._tests: list[AntaTestDefinition] = []
@@ -314,8 +323,10 @@ def parse(filename: str | Path, file_format: Literal["yaml", "json"] = "yaml") -
 
         Parameters
         ----------
-            filename: Path to test catalog YAML or JSON fil
-            file_format: Format of the file, either 'yaml' or 'json'
+        filename
+            Path to test catalog YAML or JSON file.
+        file_format
+            Format of the file, either 'yaml' or 'json'.
 
         """
         if file_format not in ["yaml", "json"]:
@@ -343,7 +354,8 @@ def from_dict(data: RawCatalogInput, filename: str | Path | None = None) -> Anta
 
         Parameters
         ----------
-            data: Python dictionary used to instantiate the AntaCatalog instance
+        data
+            Python dictionary used to instantiate the AntaCatalog instance.
             filename: value to be set as AntaCatalog instance attribute
 
         """
@@ -377,7 +389,8 @@ def from_list(data: ListAntaTestTuples) -> AntaCatalog:
 
         Parameters
         ----------
-            data: Python list used to instantiate the AntaCatalog instance
+        data
+            Python list used to instantiate the AntaCatalog instance.
 
         """
         tests: list[AntaTestDefinition] = []
@@ -394,10 +407,12 @@ def merge_catalogs(cls, catalogs: list[AntaCatalog]) -> AntaCatalog:
 
         Parameters
         ----------
-            catalogs: A list of AntaCatalog instances to merge.
+        catalogs
+            A list of AntaCatalog instances to merge.
 
         Returns
         -------
+        AntaCatalog
             A new AntaCatalog instance containing the tests of all the input catalogs.
         """
         combined_tests = list(chain(*(catalog.tests for catalog in catalogs)))
@@ -408,10 +423,12 @@ def merge(self, catalog: AntaCatalog) -> AntaCatalog:
 
         Parameters
         ----------
-            catalog: AntaCatalog instance to merge to this instance.
+        catalog
+            AntaCatalog instance to merge to this instance.
 
         Returns
         -------
+        AntaCatalog
             A new AntaCatalog instance containing the tests of the two instances.
         """
         # TODO: Use a decorator to deprecate this method instead. See https://github.com/aristanetworks/anta/issues/754
@@ -427,6 +444,7 @@ def dump(self) -> AntaCatalogFile:
 
         Returns
         -------
+        AntaCatalogFile
             An AntaCatalogFile instance containing tests of this AntaCatalog instance.
         """
         root: dict[ImportString[Any], list[AntaTestDefinition]] = {}
@@ -466,17 +484,21 @@ def get_tests_by_tags(self, tags: set[str], *, strict: bool = False) -> set[Anta
 
         Parameters
         ----------
-            tags: The tags to filter tests by. If empty, return all tests without tags.
-            strict: If True, returns only tests that contain all specified tags (intersection).
-                    If False, returns tests that contain any of the specified tags (union).
+        tags
+            The tags to filter tests by. If empty, return all tests without tags.
+        strict
+            If True, returns only tests that contain all specified tags (intersection).
+            If False, returns tests that contain any of the specified tags (union).
 
         Returns
         -------
-            set[AntaTestDefinition]: A set of tests that match the given tags.
+        set[AntaTestDefinition]
+            A set of tests that match the given tags.
 
         Raises
         ------
-            ValueError: If the indexes have not been built prior to method call.
+        ValueError
+            If the indexes have not been built prior to method call.
         """
         if not self.indexes_built:
             msg = "Indexes have not been built yet. Call build_indexes() first."

anta/cli/get/utils.py

@@ -84,18 +84,24 @@ def get_cv_token(cvp_ip: str, cvp_username: str, cvp_password: str, *, verify_ce
 
     Parameters
     ----------
-        cvp_ip: IP address of CloudVision.
-        cvp_username: Username to connect to CloudVision.
-        cvp_password: Password to connect to CloudVision.
-        verify_cert: Enable or disable certificate verification when connecting to CloudVision.
+    cvp_ip
+        IP address of CloudVision.
+    cvp_username
+        Username to connect to CloudVision.
+    cvp_password
+        Password to connect to CloudVision.
+    verify_cert
+        Enable or disable certificate verification when connecting to CloudVision.
 
     Returns
     -------
-        token(str): The token to use in further API calls to CloudVision.
+    str
+        The token to use in further API calls to CloudVision.
 
     Raises
     ------
-        requests.ssl.SSLError: If the certificate verification fails
+    requests.ssl.SSLError
+        If the certificate verification fails.
 
     """
     # use CVP REST API to generate a token
@@ -163,9 +169,12 @@ def create_inventory_from_ansible(inventory: Path, output: Path, ansible_group:
 
     Parameters
     ----------
-        inventory: Ansible Inventory file to read
-        output: ANTA inventory file to generate.
-        ansible_group: Ansible group from where to extract data.
+    inventory
+        Ansible Inventory file to read.
+    output
+        ANTA inventory file to generate.
+    ansible_group
+        Ansible group from where to extract data.
 
     """
     try:

anta/cli/nrfu/utils.py

@@ -147,8 +147,10 @@ def save_markdown_report(ctx: click.Context, md_output: pathlib.Path) -> None:
 
     Parameters
     ----------
-        ctx: Click context containing the result manager.
-        md_output: Path to save the markdown report.
+    ctx
+        Click context containing the result manager.
+    md_output
+        Path to save the markdown report.
     """
     try:
         MDReportGenerator.generate(results=_get_result_manager(ctx), md_filename=md_output)

anta/cli/utils.py

@@ -62,7 +62,8 @@ def exit_with_code(ctx: click.Context) -> None:
 
     Parameters
     ----------
-        ctx: Click Context
+    ctx
+        Click Context.
 
     """
     if ctx.obj.get("ignore_status"):

anta/custom_types.py

@@ -66,9 +66,9 @@ def interface_case_sensitivity(v: str) -> str:
 
     Examples
     --------
-         - ethernet -> Ethernet
-         - vlan -> Vlan
-         - loopback -> Loopback
+    - ethernet -> Ethernet
+    - vlan -> Vlan
+    - loopback -> Loopback
 
     """
     if isinstance(v, str) and v != "" and not v[0].isupper():
@@ -81,10 +81,10 @@ def bgp_multiprotocol_capabilities_abbreviations(value: str) -> str:
 
     Examples
     --------
-        - IPv4 Unicast
-        - L2vpnEVPN
-        - ipv4 MPLS Labels
-        - ipv4Mplsvpn
+    - IPv4 Unicast
+    - L2vpnEVPN
+    - ipv4 MPLS Labels
+    - ipv4Mplsvpn
 
     """
     patterns = {

anta/decorators.py

@@ -22,11 +22,13 @@ def deprecated_test(new_tests: list[str] | None = None) -> Callable[[F], F]:
 
     Parameters
     ----------
-        new_tests: A list of new test classes that should replace the deprecated test.
+    new_tests
+        A list of new test classes that should replace the deprecated test.
 
     Returns
     -------
-        Callable[[F], F]: A decorator that can be used to wrap test functions.
+    Callable[[F], F]
+        A decorator that can be used to wrap test functions.
 
     """
 
@@ -35,11 +37,13 @@ def decorator(function: F) -> F:
 
         Parameters
         ----------
-            function: The test function to be decorated.
+        function
+            The test function to be decorated.
 
         Returns
         -------
-            F: The decorated function.
+        F
+            The decorated function.
 
         """
 
@@ -66,11 +70,13 @@ def skip_on_platforms(platforms: list[str]) -> Callable[[F], F]:
 
     Parameters
     ----------
-        platforms: List of hardware models on which the test should be skipped.
+    platforms
+        List of hardware models on which the test should be skipped.
 
     Returns
     -------
-        Callable[[F], F]: A decorator that can be used to wrap test functions.
+    Callable[[F], F]
+        A decorator that can be used to wrap test functions.
 
     """
 
@@ -79,11 +85,13 @@ def decorator(function: F) -> F:
 
         Parameters
         ----------
-            function: The test function to be decorated.
+        function
+            The test function to be decorated.
 
         Returns
         -------
-            F: The decorated function.
+        F
+            The decorated function.
 
         """