doc: Make API documentation great again (#797)

* chore: update griffe requirement from <1.0.0,>=0.46 to >=0.46,<2.0.0 Updates the requirements on [griffe](https://github.com/mkdocstrings/griffe) to permit the latest version. - [Release notes](https://github.com/mkdocstrings/griffe/releases) - [Changelog](https://github.com/mkdocstrings/griffe/blob/main/CHANGELOG.md) - [Commits](mkdocstrings/griffe@0.46.0...1.1.0) --- updated-dependencies: - dependency-name: griffe dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> * Doc: Fix documentation * Refactor: Address PR comments * Doc: Address more PR comments * chore: Add python handler min version for mkdocstring * Apply suggestions from code review * Update anta/models.py * Update anta/reporter/csv_reporter.py * doc: Adjust pyproject.toml as per ruff doc * doc: Reading the doc better * Fix doc * doc: Better ruff config * doc: Fix css issue * Update pyproject.toml --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: gmuloc <[email protected]> Co-authored-by: Carl Baillargeon <[email protected]>
aristanetworks · Sep 11, 2024 · e32821d · e32821d
1 parent 9f433ce
commit e32821d
Show file tree

Hide file tree

Showing 38 changed files with 766 additions and 452 deletions.
diff --git a/anta/catalog.py b/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)))
@@ -406,12 +421,18 @@ def merge_catalogs(cls, catalogs: list[AntaCatalog]) -> AntaCatalog:
     def merge(self, catalog: AntaCatalog) -> AntaCatalog:
         """Merge two AntaCatalog instances.
 
+        Warning
+        -------
+        This method is deprecated and will be removed in ANTA v2.0. Use `AntaCatalog.merge_catalogs()` instead.
+
         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 +448,7 @@ def dump(self) -> AntaCatalogFile:
 
         Returns
         -------
+        AntaCatalogFile
             An AntaCatalogFile instance containing tests of this AntaCatalog instance.
         """
         root: dict[ImportString[Any], list[AntaTestDefinition]] = {}
@@ -441,7 +463,9 @@ def build_indexes(self, filtered_tests: set[str] | None = None) -> None:
         If a `filtered_tests` set is provided, only the tests in this set will be indexed.
 
         This method populates two attributes:
+
         - tag_to_tests: A dictionary mapping each tag to a set of tests that contain it.
+
         - tests_without_tags: A set of tests that do not have any tags.
 
         Once the indexes are built, the `indexes_built` attribute is set to True.
@@ -466,17 +490,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."

diff --git a/anta/cli/get/utils.py b/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:

diff --git a/anta/cli/nrfu/utils.py b/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)

diff --git a/anta/cli/utils.py b/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"):

diff --git a/anta/custom_types.py b/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 = {

diff --git a/anta/decorators.py b/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.
 
         """