doc: Nicer FAQ (#596)

aristanetworks · Mar 21, 2024 · f1beef2 · f1beef2
1 parent 1a16cdf
commit f1beef2
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 33 deletions.
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,67 +1,79 @@
+---
+toc_depth: 4
+---
 <!--
   ~ 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.
   -->
+<style>
+  h4 {
+    display: none;
+  }
+</style>
 
 # Frequently Asked Questions (FAQ)
 
-## Why am I seeing an `ImportError` related to `urllib3` when running ANTA?
 
-When running the `anta --help` command, some users might encounter the following error:
+## `ImportError` related to `urllib3`
+??? faq "`ImportError` related to `urllib3` when running ANTA"
 
-```bash
-ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'OpenSSL 1.0.2k-fips  26 Jan 2017'. See: https://github.com/urllib3/urllib3/issues/2168
-```
+    When running the `anta --help` command, some users might encounter the following error:
 
-This error arises due to a compatibility issue between `urllib3` v2.0 and older versions of OpenSSL.
+    ```bash
+    ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'OpenSSL 1.0.2k-fips  26 Jan 2017'. See: https://github.com/urllib3/urllib3/issues/2168
+    ```
 
-#### How can I resolve this error?
+    This error arises due to a compatibility issue between `urllib3` v2.0 and older versions of OpenSSL.
 
-1. _Workaround_: Downgrade `urllib3`
+    ### Solution
 
-    If you need a quick fix, you can temporarily downgrade the `urllib3` package:
+    1. _Workaround_: Downgrade `urllib3`
 
-    ```bash
-    pip3 uninstall urllib3
+        If you need a quick fix, you can temporarily downgrade the `urllib3` package:
 
-    pip3 install urllib3==1.26.15
-    ```
+        ```bash
+        pip3 uninstall urllib3
 
-2. _Recommended_: Upgrade System or Libraries:
+        pip3 install urllib3==1.26.15
+        ```
 
-    As per the [urllib3 v2 migration guide](https://urllib3.readthedocs.io/en/latest/v2-migration-guide.html), the root cause of this error is an incompatibility with older OpenSSL versions. For example, users on RHEL7 might consider upgrading to RHEL8, which supports the required OpenSSL version.
+    2. _Recommended_: Upgrade System or Libraries:
 
-## Why am I seeing `AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'` when running ANTA
+            As per the [urllib3 v2 migration guide](https://urllib3.readthedocs.io/en/latest/v2-migration-guide.html), the root cause of this error is an incompatibility with older OpenSSL versions. For example, users on RHEL7 might consider upgrading to RHEL8, which supports the required OpenSSL version.
 
-When running the `anta` commands after installation, some users might encounter the following error:
+##`AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'`
+??? faq "`AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'` when running ANTA"
 
-```bash
-AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'
-```
+    When running the `anta` commands after installation, some users might encounter the following error:
 
-The error is a result of incompatibility between `cryptography` and `pyopenssl` when installing `asyncssh` which is a requirement of ANTA.
+    ```bash
+    AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'
+    ```
 
-#### How can I resolve this error?
+    The error is a result of incompatibility between `cryptography` and `pyopenssl` when installing `asyncssh` which is a requirement of ANTA.
 
-1. Upgrade `pyopenssl`
+    ### Solution
 
-    ```bash
-    pip install -U pyopenssl>22.0
-    ```
+    1. Upgrade `pyopenssl`
+
+        ```bash
+        pip install -U pyopenssl>22.0
+        ```
 
 ## `__NSCFConstantString initialize` error on OSX
+??? faq "`__NSCFConstantString initialize` error on OSX"
 
-This error occurs because of added security to restrict multithreading in macOS High Sierra and later versions of macOS. https://www.wefearchange.org/2018/11/forkmacos.rst.html
+    This error occurs because of added security to restrict multithreading in macOS High Sierra and later versions of macOS. https://www.wefearchange.org/2018/11/forkmacos.rst.html
 
-#### How can I resolve this error?
+    ### Solution
 
-1. Set the following environment variable
+    1. Set the following environment variable
 
-    ```bash
-    export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
-    ```
+        ```bash
+        export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
+        ```
 
-## Still facing issues?
+# Still facing issues?
 
 If you've tried the above solutions and continue to experience problems, please report the issue in our [GitHub repository](https://github.com/arista-netdevops-community/anta).
diff --git a/docs/overrides/partials/toc-item.html b/docs/overrides/partials/toc-item.html
@@ -0,0 +1,21 @@
+<!-- Courtesy of https://github.com/squidfunk/mkdocs-material/issues/4827#issuecomment-1869812019 -->
+<li class="md-nav__item">
+    <a href="{{ toc_item.url }}" class="md-nav__link">
+      <span class="md-ellipsis">
+        {{ toc_item.title }}
+      </span>
+    </a>
+
+    <!-- Table of contents list -->
+    {% if toc_item.children %}
+      <nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
+        <ul class="md-nav__list">
+          {% for toc_item in toc_item.children %}
+          {% if not page.meta.toc_depth or toc_item.level <= page.meta.toc_depth %}
+            {% include "partials/toc-item.html" %}
+          {% endif %}
+          {% endfor %}
+        </ul>
+      </nav>
+    {% endif %}
+  </li>