From 3dede8b5459a62211512fd3d6fdf935c738e26d7 Mon Sep 17 00:00:00 2001
From: Carl Baillargeon <carl.baillargeon@arista.com>
Date: Thu, 7 Nov 2024 14:47:07 -0500
Subject: [PATCH] Update doc

---
 docs/advanced_usages/scaling.md | 55 ++++++++++++++++++++++++++++++++-
 docs/faq.md                     |  6 ++++
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/docs/advanced_usages/scaling.md b/docs/advanced_usages/scaling.md
index 440625d99..be1fab906 100644
--- a/docs/advanced_usages/scaling.md
+++ b/docs/advanced_usages/scaling.md
@@ -29,8 +29,10 @@
       - [Tag-Based Implementation](#tag-based-implementation)
     - [Performance Considerations](#performance-considerations)
       - [Parallel Job Control](#parallel-job-control)
+      - [JSON vs YAML](#json-vs-yaml)
     - [Results Management](#results-management)
   - [🎉 Conclusion](#-conclusion)
+  - [📚 References](#-references)
 
 ## 📖 Introduction
 
@@ -492,6 +494,28 @@ The `-j` option in `GNU Parallel` controls the number of concurrent jobs. Consid
      - Each ANTA instance requires memory
      - Monitor system resources during execution using `htop` or similar tools
 
+#### JSON vs YAML
+
+When working with large catalogs and inventories, using JSON format instead of YAML can provide better performance as ANTA loads JSON files more efficiently. If you choose to use JSON:
+
+- Convert your YAML files to JSON (you can use `yq` for this)
+- Modify the scripts to use `jq` instead of `yq`:
+
+  ```bash
+  # For device-based implementation
+  NODE_NAMES=$(jq -r '.anta_inventory.hosts[].name' < "anta_inventory.json")
+
+  # For tag-based implementation
+  TAGS=$(jq -r '.. | select(.filters?) | .filters.tags[]' < "anta_catalog.json" | sort -u)
+  ```
+
+  Example of converting YAML to JSON:
+
+  ```bash
+  yq -o=json eval 'anta_inventory.yaml' > anta_inventory.json
+  yq -o=json eval 'anta_catalog.yaml' > anta_catalog.json
+  ```
+
 ### Results Management
 
 ANTA can output results in various formats:
@@ -563,6 +587,9 @@ ANTA can output results in various formats:
     xml.write("nrfu.xml", pretty=True)
     ```
 
+    !!! tip "CI/CD Integration"
+        This report format can be used with CI/CD tools like Jenkins, GitLab, or GitHub Actions.
+
 ## 🎉 Conclusion
 
 By implementing these scaling strategies, you can efficiently run ANTA tests on large network fabrics. The combination of parallel execution, optimized catalogs, and proper resource management ensures fast and reliable network validation.
@@ -578,5 +605,31 @@ Remember to:
     Performance tuning can be complex and highly dependent on your specific deployment. Don't hesitate to:
 
     - 📞 Reach out to your Arista SE for guidance
-    - 📝 Document your specific use case on GitHub
+    - 📝 Document your specific use case on [GitHub](https://github.com/aristanetworks/anta)
     - 🔍 Share your findings with the community
+
+## 📚 References
+
+- **Python AsyncIO**
+  - [AsyncIO Documentation](https://docs.python.org/3/library/asyncio.html)
+  - [AsyncIO Event Loop](https://docs.python.org/3/library/asyncio-eventloop.html)
+  - [AsyncIO Tasks and Coroutines](https://docs.python.org/3/library/asyncio-task.html)
+
+- **HTTPX**
+  - [HTTPX Documentation](https://www.python-httpx.org/)
+  - [Timeouts](https://www.python-httpx.org/advanced/timeouts/)
+  - [Resource Limits](https://www.python-httpx.org/advanced/resource-limits/)
+
+- **GNU Parallel**
+  - [GNU Parallel Documentation](https://www.gnu.org/software/parallel/)
+  - [GNU Parallel Tutorial](https://www.gnu.org/software/parallel/parallel_tutorial.html)
+
+- **JSON and YAML Processing**
+  - [jq Manual](https://jqlang.github.io/jq/manual/)
+  - [jq GitHub Repository](https://github.com/jqlang/jq)
+  - [yq Documentation](https://mikefarah.gitbook.io/yq/)
+  - [yq GitHub Repository](https://github.com/mikefarah/yq/)
+
+- **JUnit/xUnit Result XML Parser**
+  - [junitparser Documentation](https://junitparser.readthedocs.io/en/latest/)
+  - [junitparser GitHub Repository](https://github.com/weiwei/junitparser)
diff --git a/docs/faq.md b/docs/faq.md
index 7a5866337..443dd08f3 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -43,6 +43,9 @@ anta_title: Frequently Asked Questions (FAQ)
     The `user` is the one with which the ANTA process is started.
     The `value` is the new hard limit. The maximum value depends on the system. A hard limit of 16384 should be sufficient for ANTA to run in most high scale scenarios. After creating this file, log out the current session and log in again.
 
+    !!! tip "Large Scale Deployments"
+        For detailed information about managing file descriptors and other resource limits in large scale deployments, please refer to the [Scaling ANTA](advanced_usages/scaling.md#resource-management) guide.
+
 ## `Timeout` error in the logs
 
 ???+ faq "`Timeout` error in the logs"
@@ -62,6 +65,9 @@ anta_title: Frequently Asked Questions (FAQ)
     The previous command set a couple of options for ANTA NRFU, one them being the `timeout` command, by default, when running ANTA from CLI, it is set to 30s.
     The timeout is increased to 50s to allow ANTA to wait for API calls a little longer.
 
+    !!! tip "Advanced Timeout Configuration"
+        For comprehensive information about timeout configuration and optimization in large scale environments, see the [Timeouts Configuration](advanced_usages/scaling.md#timeouts-configuration) section in the Scaling ANTA guide. The guide provides detailed explanations of different timeout types and recommended values for various deployment scenarios.
+
 ## `ImportError` related to `urllib3`
 
 ???+ faq "`ImportError` related to `urllib3` when running ANTA"