doc: Add documentation for runner.md under api (#652)

Co-authored-by: Thomas Grimonet <[email protected]>

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
     rev: v4.4.0
     hooks:
       - id: trailing-whitespace
+        exclude: docs/.*.svg
       - id: end-of-file-fixer
       - id: check-added-large-files
         exclude: tests/data/.*$

anta/result_manager/__init__.py

@@ -48,19 +48,25 @@ class ResultManager:
             manager.results
             [
                 TestResult(
-                    host=IPv4Address('192.168.0.10'),
-                    test='VerifyNTP',
-                    result='failure',
-                    message="device is not running NTP correctly"
+                    name="pf1",
+                    test="VerifyZeroTouch",
+                    categories=["configuration"],
+                    description="Verifies ZeroTouch is disabled",
+                    result="success",
+                    messages=[],
+                    custom_field=None,
                 ),
                 TestResult(
-                    host=IPv4Address('192.168.0.10'),
-                    test='VerifyEOSVersion',
-                    result='success',
-                    message=None
+                    name="pf1",
+                    test='VerifyNTP',
+                    categories=["software"],
+                    categories=['system'],
+                    description='Verifies if NTP is synchronised.',
+                    result='failure',
+                    messages=["The device is not synchronized with the configured NTP server(s): 'NTP is disabled.'"],
+                    custom_field=None,
                 ),
             ]
-
     """
 
     def __init__(self) -> None:

docs/api/runner.md

@@ -0,0 +1,9 @@
+<!--
+  ~ 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.runner
+    options:
+        filters: ["!^_[^_]", "!__str__"]

docs/getting-started.md

@@ -13,7 +13,7 @@ This section shows how to use ANTA with basic configuration. All examples are ba
 The easiest way to install ANTA package is to run Python (`>=3.9`) and its pip package to install:
 
 ```bash
-pip install anta
+pip install anta[cli]
 ```
 
 For more details about how to install package, please see the [requirements and installation](./requirements-and-installation.md) section.
@@ -121,6 +121,14 @@ anta.tests.configuration:
 
 ## Test your network
 
+### Basic usage in a python script
+
+```python
+--8<-- "anta_runner.py"
+```
+
+### CLI
+
 ANTA comes with a generic CLI entrypoint to run tests in your network. It requires an inventory file as well as a test catalog.
 
 This entrypoint has multiple options to manage test coverage and reporting.
@@ -135,7 +143,7 @@ This entrypoint has multiple options to manage test coverage and reporting.
 
 To run the NRFU, you need to select an output format amongst ["json", "table", "text", "tpl-report"]. For a first usage, `table` is recommended.  By default all test results for all devices are rendered but it can be changed to a report per test case or per host
 
-### Default report using table
+#### Default report using table
 
 ```bash
 anta nrfu \
@@ -176,7 +184,7 @@ anta nrfu \
 └───────────┴──────────────────────────┴─────────────┴──────────────────┴──────────────────────────────────────────────────────────────────────┴───────────────┘
 ```
 
-### Report in text mode
+#### Report in text mode
 
 ```bash
 $ anta nrfu \
@@ -206,7 +214,7 @@ leaf01 :: VerifyMlagConfigSanity :: SKIPPED (MLAG is disabled)
 [...]
 ```
 
-### Report in JSON format
+#### Report in JSON format
 
 ```bash
 $ anta nrfu \

examples/anta_runner.py

@@ -0,0 +1,67 @@
+# 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.
+"""Example script for ANTA.
+
+usage:
+
+python anta_runner.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from anta.catalog import AntaCatalog
+from anta.cli.nrfu.utils import anta_progress_bar
+from anta.inventory import AntaInventory
+from anta.logger import Log, setup_logging
+from anta.models import AntaTest
+from anta.result_manager import ResultManager
+from anta.runner import main as anta_runner
+
+# setup logging
+setup_logging(Log.INFO, Path("/tmp/anta.log"))
+LOGGER = logging.getLogger()
+SCRIPT_LOG_PREFIX = "[bold magenta][ANTA RUNNER SCRIPT][/] "  # For convenience purpose - there are nicer way to do this.
+
+
+# NOTE: The inventory and catalog files are not delivered with this script
+USERNAME = "admin"
+PASSWORD = "admin"
+CATALOG_PATH = Path("/tmp/anta_catalog.yml")
+INVENTORY_PATH = Path("/tmp/anta_inventory.yml")
+
+# Load catalog file
+try:
+    catalog = AntaCatalog.parse(CATALOG_PATH)
+except Exception:
+    LOGGER.exception("%s Catalog failed to load!", SCRIPT_LOG_PREFIX)
+    sys.exit(1)
+LOGGER.info("%s Catalog loaded!", SCRIPT_LOG_PREFIX)
+
+# Load inventory
+try:
+    inventory = AntaInventory.parse(INVENTORY_PATH, username=USERNAME, password=PASSWORD)
+except Exception:
+    LOGGER.exception("%s Inventory failed to load!", SCRIPT_LOG_PREFIX)
+    sys.exit(1)
+LOGGER.info("%s Inventory loaded!", SCRIPT_LOG_PREFIX)
+
+# Create result manager object
+manager = ResultManager()
+
+# Launch ANTA
+LOGGER.info("%s  Starting ANTA runner...", SCRIPT_LOG_PREFIX)
+with anta_progress_bar() as AntaTest.progress:
+    # Set dry_run to True to avoid connecting to the devices
+    asyncio.run(anta_runner(manager, inventory, catalog, dry_run=False))
+
+LOGGER.info("%s ANTA run completed!", SCRIPT_LOG_PREFIX)
+
+# Manipulate the test result object
+for test_result in manager.results:
+    LOGGER.info("%s %s:%s:%s", SCRIPT_LOG_PREFIX, test_result.name, test_result.test, test_result.result)

mkdocs.yml

@@ -148,7 +148,9 @@ markdown_extensions:
       baselevel: 3
   - pymdownx.highlight
   - pymdownx.snippets:
-      base_path: docs/snippets
+      base_path:
+        - docs/snippets
+        - examples
   - pymdownx.superfences
   - pymdownx.superfences
   - pymdownx.tabbed:
@@ -208,18 +210,19 @@ nav:
     - VXLAN: api/tests.vxlan.md
     - VLAN: api/tests.vlan.md
   - API Documentation:
+    - Device: api/device.md
     - Inventory:
       - Inventory module: api/inventory.md
       - Inventory models: api/inventory.models.input.md
     - Test Catalog: api/catalog.md
-    - Device: api/device.md
     - Test:
       - Test models: api/models.md
       - Input Types:  api/types.md
     - Result Manager:
       - Result Manager module: api/result_manager.md
       - Result Manager models: api/result_manager_models.md
     - Report Manager: api/report_manager.md
+    - Runner: api/runner.md
   - Troubleshooting: troubleshooting.md
   - Contributions: contribution.md
   - FAQ: faq.md

pyproject.toml

@@ -312,7 +312,7 @@ exclude = [
     "site-packages",
     "venv",
     ".github",
-    "aioeapi.py" # Remove this when https://github.com/jeremyschulman/aio-eapi/pull/13 is merged
+    "aioeapi.py", # Remove this when https://github.com/jeremyschulman/aio-eapi/pull/13 is merged
 ]
 
 line-length = 165
@@ -414,6 +414,11 @@ runtime-evaluated-base-classes = ["pydantic.BaseModel", "anta.models.AntaTest.In
 "anta/inventory/__init__.py" = [
   "PLR0913",     # Ok to have more than 5 arguments in the AntaInventory class
 ]
+"examples/anta_runner.py" = [  # This is an example script and linked in  snippets
+  "S108",   # Probable insecure usage of temporary file or directory
+  "S105",   # Possible hardcoded password
+  "INP001", # Implicit packages
+]
 
 ################################
 # Pylint
@@ -447,4 +452,5 @@ extension-pkg-whitelist="pydantic"
 ignore-paths = [
   "^tests/units/anta_tests/.*/data.py$",
   "^tests/units/anta_tests/routing/.*/data.py$",
+  "^docs/scripts/anta_runner.py",
 ]