doc: Clean doc pre-release (#876)

--------- Co-authored-by: Carl Baillargeon <[email protected]> Co-authored-by: Matthieu Tâche <[email protected]>
aristanetworks · Oct 11, 2024 · 7880064 · 7880064
1 parent 5483b97
commit 7880064
Show file tree

Hide file tree

Showing 24 changed files with 329 additions and 276 deletions.
diff --git a/anta/reporter/__init__.py b/anta/reporter/__init__.py
@@ -105,7 +105,7 @@ def _color_result(self, status: AntaTestStatus) -> str:
     def report_all(self, manager: ResultManager, title: str = "All tests results") -> Table:
         """Create a table report with all tests for one or all devices.
 
-        Create table with full output: Host / Test / Status / Message
+        Create table with full output: Device | Test Name | Test Status | Message(s) | Test description | Test category
 
         Parameters
         ----------
@@ -141,7 +141,8 @@ def report_summary_tests(
     ) -> Table:
         """Create a table report with result aggregated per test.
 
-        Create table with full output: Test | Number of success | Number of failure | Number of error | List of nodes in error or failure
+        Create table with full output:
+        Test Name | # of success | # of skipped | # of failure | # of errors | List of failed or error nodes
 
         Parameters
         ----------
@@ -187,7 +188,7 @@ def report_summary_devices(
     ) -> Table:
         """Create a table report with result aggregated per device.
 
-        Create table with full output: Host | Number of success | Number of failure | Number of error | List of nodes in error or failure
+        Create table with full output: Device | # of success | # of skipped | # of failure | # of errors | List of failed or error test cases
 
         Parameters
         ----------

diff --git a/anta/reporter/md_reporter.py b/anta/reporter/md_reporter.py
@@ -112,8 +112,8 @@ def generate_heading_name(self) -> str:
 
         Example
         -------
-        - `ANTAReport` will become ANTA Report.
-        - `TestResultsSummary` will become Test Results Summary.
+        - `ANTAReport` will become `ANTA Report`.
+        - `TestResultsSummary` will become `Test Results Summary`.
         """
         class_name = self.__class__.__name__
 
@@ -153,7 +153,7 @@ def write_heading(self, heading_level: int) -> None:
 
         Example
         -------
-        ## Test Results Summary
+        `## Test Results Summary`
         """
         # Ensure the heading level is within the valid range of 1 to 6
         heading_level = max(1, min(heading_level, 6))

diff --git a/docs/advanced_usages/as-python-lib.md b/docs/advanced_usages/as-python-lib.md
@@ -44,98 +44,14 @@ The [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) class is a
 ### Parse an ANTA inventory file
 
 ```python
-"""
-This script parses an ANTA inventory file, connects to devices and print their status.
-"""
-import asyncio
-
-from anta.inventory import AntaInventory
-
-
-async def main(inv: AntaInventory) -> None:
-    """
-    Take an AntaInventory and:
-    1. try to connect to every device in the inventory
-    2. print a message for every device connection status
-    """
-    await inv.connect_inventory()
-
-    for device in inv.values():
-        if device.established:
-            print(f"Device {device.name} is online")
-        else:
-            print(f"Could not connect to device {device.name}")
-
-if __name__ == "__main__":
-    # Create the AntaInventory instance
-    inventory = AntaInventory.parse(
-        filename="inv.yml",
-        username="arista",
-        password="@rista123",
-    )
-
-    # Run the main coroutine
-    res = asyncio.run(main(inventory))
+--8<-- "parse_anta_inventory_file.py"
 ```
 
-??? note "How to create your inventory file"
+!!! note "How to create your inventory file"
     Please visit this [dedicated section](../usage-inventory-catalog.md) for how to use inventory and catalog files.
 
 ### Run EOS commands
 
 ```python
-"""
-This script runs a list of EOS commands on reachable devices.
-"""
-# This is needed to run the script for python < 3.10 for typing annotations
-from __future__ import annotations
-
-import asyncio
-from pprint import pprint
-
-from anta.inventory import AntaInventory
-from anta.models import AntaCommand
-
-
-async def main(inv: AntaInventory, commands: list[str]) -> dict[str, list[AntaCommand]]:
-    """
-    Take an AntaInventory and a list of commands as string and:
-    1. try to connect to every device in the inventory
-    2. collect the results of the commands from each device
-
-    Returns:
-      a dictionary where key is the device name and the value is the list of AntaCommand ran towards the device
-    """
-    await inv.connect_inventory()
-
-    # Make a list of coroutine to run commands towards each connected device
-    coros = []
-    # dict to keep track of the commands per device
-    result_dict = {}
-    for name, device in inv.get_inventory(established_only=True).items():
-        anta_commands = [AntaCommand(command=command, ofmt="json") for command in commands]
-        result_dict[name] = anta_commands
-        coros.append(device.collect_commands(anta_commands))
-
-    # Run the coroutines
-    await asyncio.gather(*coros)
-
-    return result_dict
-
-
-if __name__ == "__main__":
-    # Create the AntaInventory instance
-    inventory = AntaInventory.parse(
-        filename="inv.yml",
-        username="arista",
-        password="@rista123",
-    )
-
-    # Create a list of commands with json output
-    commands = ["show version", "show ip bgp summary"]
-
-    # Run the main asyncio  entry point
-    res = asyncio.run(main(inventory, commands))
-
-    pprint(res)
+--8<-- "run_eos_commands.py"
 ```
diff --git a/docs/advanced_usages/custom-tests.md b/docs/advanced_usages/custom-tests.md
@@ -71,9 +71,6 @@ Full AntaTest API documentation is available in the [API documentation section](
 
 ### Instance Attributes
 
-!!! info
-    You can access an instance attribute in your code using the `self` reference. E.g. you can access the test input values using `self.inputs`.
-
 ::: anta.models.AntaTest
     options:
         show_docstring_attributes: true

diff --git a/docs/api/csv_reporter.md b/docs/api/csv_reporter.md
@@ -0,0 +1,13 @@
+---
+anta_title: CSV Reporter
+---
+<!--
+  ~ Copyright (c) 2023-2024 Arista Networks, Inc.
+  ~ Use of this source code is governed by the Apache License 2.0
+  ~ that can be found in the LICENSE file.
+  -->
+
+::: anta.reporter.csv_reporter
+    options:
+        show_root_heading: false
+        show_root_toc_entry: false
diff --git a/docs/api/md_reporter.md b/docs/api/md_reporter.md
@@ -0,0 +1,13 @@
+---
+anta_title: Markdown Reporter
+---
+<!--
+  ~ Copyright (c) 2023-2024 Arista Networks, Inc.
+  ~ Use of this source code is governed by the Apache License 2.0
+  ~ that can be found in the LICENSE file.
+  -->
+
+::: anta.reporter.md_reporter
+    options:
+        show_root_heading: false
+        show_root_toc_entry: false
diff --git a/docs/api/report_manager.md → docs/api/reporters.md b/docs/api/report_manager.md → docs/api/reporters.md
@@ -4,4 +4,7 @@
   ~ that can be found in the LICENSE file.
   -->
 
-### ::: anta.reporter.ReportTable
+::: anta.reporter
+    options:
+        show_root_heading: false
+        show_root_toc_entry: false
diff --git a/docs/api/tests.md b/docs/api/tests.md
@@ -18,7 +18,7 @@ Here are the tests that we currently provide:
 - [BFD](tests.bfd.md)
 - [Configuration](tests.configuration.md)
 - [Connectivity](tests.connectivity.md)
-- [Field Notice](tests.field_notices.md)
+- [Field Notices](tests.field_notices.md)
 - [Flow Tracking](tests.flow_tracking.md)
 - [GreenT](tests.greent.md)
 - [Hardware](tests.hardware.md)
@@ -32,6 +32,7 @@ Here are the tests that we currently provide:
 - [Router Path Selection](tests.path_selection.md)
 - [Routing Generic](tests.routing.generic.md)
 - [Routing BGP](tests.routing.bgp.md)
+- [Routing ISIS](tests.routing.isis.md)
 - [Routing OSPF](tests.routing.ospf.md)
 - [Security](tests.security.md)
 - [Services](tests.services.md)

diff --git a/docs/api/tests.routing.bgp.md b/docs/api/tests.routing.bgp.md
@@ -18,3 +18,4 @@ anta_title: ANTA catalog for BGP tests
       filters:
         - "!test"
         - "!render"
+        - "!^_[^_]"
diff --git a/docs/api/tests.routing.isis.md b/docs/api/tests.routing.isis.md
@@ -18,3 +18,4 @@ anta_title: ANTA catalog for IS-IS tests
       filters:
         - "!test"
         - "!render"
+        - "!^_[^_]"
diff --git a/docs/api/tests.routing.ospf.md b/docs/api/tests.routing.ospf.md
@@ -18,3 +18,4 @@ anta_title: ANTA catalog for OSPF tests
       filters:
         - "!test"
         - "!render"
+        - "!^_[^_]"
diff --git a/docs/cli/debug.md b/docs/cli/debug.md
@@ -15,7 +15,7 @@ The ANTA CLI includes a set of debugging tools, making it easier to build and te
 These tools are especially helpful in building the tests, as they give a visual access to the output received from the eAPI. They also facilitate the extraction of output content for use in unit tests, as described in our [contribution guide](../contribution.md).
 
 !!! warning
-    The `debug` tools require a device from your inventory. Thus, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#device-inventory).
+    The `debug` tools require a device from your inventory. Thus, you must use a valid [ANTA Inventory](../usage-inventory-catalog.md#device-inventory).
 
 ## Executing an EOS command
 
@@ -160,11 +160,11 @@ Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A
 }
 ```
 
+### Example of multiple arguments
+
 !!! warning
     If multiple arguments of the same key are provided, only the last argument value will be kept in the template parameters.
 
-### Example of multiple arguments
-
 ```bash
 anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 --device DC1-SPINE1    
 > {'dst': '8.8.8.8', 'src': 'Loopback0'}