Minor doc cleanup

docs/conf.py

@@ -84,6 +84,7 @@
 }
 
 autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/installation_linux.rst

@@ -2,7 +2,7 @@ Install LISA on Linux
 =====================
 
 Minimum System Requirement
------------------------
+--------------------------
 1. Your favourite Linux distro supporting Python 3.8+
 2. Dual core processor
 3. 4 GB system memory
@@ -50,7 +50,7 @@ Install Poetry on Linux
 Poetry is used to manage Python dependencies of LISA.
 
 .. warning::
-   
+
    Please enter the root folder of LISA source code to run
    following commands to install poetry, since Poetry manages dependencies
    by the working folder.
@@ -61,18 +61,18 @@ Poetry is used to manage Python dependencies of LISA.
 
 After running this, you should see
 ``Add export PATH="/home/YOURUSERNAME/.local/bin:$PATH" to your shell configuration file``
-message on the console. Follow the message and add the necessary exports to ``$HOME/.profile`` file. 
+message on the console. Follow the message and add the necessary exports to ``$HOME/.profile`` file.
 
 .. code:: bash
 
    source $HOME/.profile
 
 [Optional] Create poetry virtual environment in the same folder as LISA for VS Code to automatically
-pick up the python environment. Run the following commands to update poetry configuration: 
+pick up the python environment. Run the following commands to update poetry configuration:
 
-.. code:: bash 
+.. code:: bash
 
-   poetry config virtualenvs.in-project true 
+   poetry config virtualenvs.in-project true
 
 Install python dependencies
 

docs/tools/test_spec_gen.py

@@ -6,6 +6,7 @@
 """
 
 import ast
+import contextlib
 import os
 from pathlib import Path
 from typing import Dict, TextIO
@@ -27,18 +28,18 @@ def update_file() -> None:
     data = load_path(TESTS)
     test_paths = [(base_path / Path(x.get("value", ""))).resolve() for x in data]
 
-    with open(file_path, "w") as test_spec:
+    with open(file_path, "w", encoding="utf-8") as test_spec:
         _write_title(test_spec)
 
         for test_path in test_paths:
             for root, _, files in os.walk(test_path):
                 for file in files:
                     if file.endswith(".py"):
-                        # print("Processing " + file)
                         test_name = Path(root) / file
-                        with open(test_name, "r") as f:
-                            contents = f.read()
-                            tree = ast.parse(contents)
+                        tree = ast.parse(
+                            test_name.read_text(encoding="utf-8"),
+                            filename=str(test_name),
+                        )
                         cls_visitor = ClassVisitor()
                         func_visitor = FuncVisitor()
                         cls_visitor.visit(tree)
@@ -57,13 +58,8 @@ def _write_title(file: TextIO) -> None:
     Args:
         file (TextIO): test spec file
     """
-    title = "Test Specification"
-    file.write(title + "\n")
-    file.write("=" * len(title) + "\n")
-    file.write("\n")
-
-    file.write("This file lists all test cases' specifications.\n")
-    file.write("\n")
+    file.write("Test Specification\n==================\n\n")
+    file.write("This file lists all test cases' specifications.\n\n")
 
 
 def _write_suite(file: TextIO, metadata: Dict[str, str]) -> None:
@@ -74,25 +70,17 @@ def _write_suite(file: TextIO, metadata: Dict[str, str]) -> None:
         file (TextIO): test spec file
         metadata (Dict[str, str]): test suite metadata
     """
-    file.write(".. _" + metadata["name"] + ":\n")  # custom anchor
-    file.write("\n")
-
-    file.write(".. class:: ")
-    file.write(metadata["name"] + "\n")  # Test Suite Name
-    file.write("    :noindex:" + "\n")
-    file.write("\n")
+    file.write(f".. _{metadata['name']}:\n\n")  # custom anchor
+    file.write(f".. class:: {metadata['name']}\n")  # Test Suite Name
+    file.write("    :noindex:\n\n")
 
     _write_description(file, metadata, True)  # Description
 
-    file.write("    :platform: ")
-    file.write("``" + "Azure, Ready" + "``\n")  # Platform
+    file.write("    :platform: ``Azure, Ready``\n")  # Platform
+    file.write(f"    :area: ``{metadata['area']}``\n")  # Area
 
-    file.write("    :area: ")
-    file.write("``" + metadata["area"] + "``\n")  # Area
-
-    file.write("    :category: ")
-    file.write("``" + metadata["category"] + "``\n")  # Category
-    file.write("\n")
+    if metadata["category"]:
+        file.write(f"    :category: ``{metadata['category']}``\n\n")  # Category
 
 
 def _write_case(file: TextIO, metadata: Dict[str, str]) -> None:
@@ -103,23 +91,17 @@ def _write_case(file: TextIO, metadata: Dict[str, str]) -> None:
         file (TextIO): test spec file
         metadata (Dict[str, str]): test case metadata
     """
-    file.write(".. _" + metadata["name"] + ":\n")  # custom anchor
-    file.write("\n")
-
-    file.write("    .. method:: ")
-    file.write(metadata["name"] + "\n")  # Test Case Name
-    file.write("        :noindex:" + "\n")
-    file.write("\n")
+    file.write(f".. _{metadata['name']}:\n\n")  # custom anchor
+    file.write(f"    .. method:: {metadata['name']}\n")  # Test Case Name
+    file.write("        :noindex:\n\n")
 
     file.write("    ")  # 1-tab indentation
     _write_description(file, metadata)  # Description
 
-    file.write("        :priority: ")
-    file.write("``" + str(metadata.get("priority", 2)) + "``\n")  # Priority
+    file.write(f"        :priority: ``{metadata.get('priority', 2)}``\n")  # Priority
 
-    if "requirement" in metadata.keys():
-        file.write("        :requirement: ")
-        file.write("``" + str(metadata["requirement"]) + "``\n")  # Requirement
+    if "requirement" in metadata:
+        file.write(f"        :requirement: ``{metadata['requirement']}``\n")
 
     file.write("\n")
 
@@ -139,22 +121,17 @@ def _write_description(
     text = metadata["description"].split("\n")
 
     # filter out empty lines
-    res = filter(lambda line: (not line.isspace()) and (not line == ""), text)
+    res = filter(lambda line: not line.isspace() and line != "", text)
     text = list(res)
 
-    index = -1
-    for line in text:
-        index += 1
+    for index, line in enumerate(text):
         # no further process
         # since spaces are automatically ignored in Sphinx
-        file.write(line)
-        file.write("\n")
-        try:
-            if text[index + 1]:  # if end of list
+        file.write(f"{line}\n")
+        with contextlib.suppress(IndexError):
+            if text[index + 1]:
                 if is_suite:
                     file.write("                  | ")
                 else:
                     file.write("                      | ")
-        except IndexError:
-            pass
     file.write("\n")

docs/tools/test_summary_gen.py

@@ -27,20 +27,18 @@ def update_summary() -> None:
 
     data = load_path(TESTS)
     test_paths = [(base_path / Path(x.get("value", ""))).resolve() for x in data]
-    with open(table_path, "w") as table:
+    with open(table_path, "w", encoding="utf-8") as table:
         _write_title(table)
 
-        index = 0
         res = []  # name, priority, platform, category, area etc.
         for test_path in test_paths:
             for root, _, files in os.walk(test_path):
                 for file in files:
                     if file.endswith(".py"):
-                        # print("Processing " + file)
                         filename = Path(root) / file
-                        with open(filename, "r") as f:
-                            contents = f.read()
-                            tree = ast.parse(contents)
+                        tree = ast.parse(
+                            filename.read_text(encoding="utf-8"), filename=str(filename)
+                        )
                         cls_visitor = ClassVisitor()
                         func_visitor = FuncVisitor()
                         cls_visitor.visit(tree)
@@ -53,13 +51,12 @@ def update_summary() -> None:
                                 suite["suite_name"] = suite["name"]
                                 del suite["name"]
                                 res.append({**suite, **case})  # merge two dicts
-        for node in res:
-            index += 1
+        for index, node in enumerate(res, start=1):
             _update_line(table, node, index)
 
         link = "https://github.com/microsoft/lisa/blob/master/Documents/LISAv2-TestCase-Statistics.md"  # noqa: E501
         table.write(".. seealso::\n")
-        table.write("    `LISAv2 Tests <" + link + ">`__\n")
+        table.write(f"    `LISAv2 Tests <{link}>`__\n")
         table.write("\n")
 
 
@@ -70,16 +67,11 @@ def _write_title(file: TextIO) -> None:
     Args:
         file (TextIO): test table
     """
-    title = "Test Cases"
-    file.write(title + "\n")
-    file.write("=" * len(title) + "\n")
-    file.write("\n")
+    file.write("Test Cases\n==========\n\n")
 
     file.write(".. list-table::\n")
     # file.write("    :widths: 5 5 25 5 10 10 10\n")  # can be configured manually
-    file.write("    :header-rows: 1\n")
-    file.write("\n")
-
+    file.write("    :header-rows: 1\n\n")
     file.write("    * - Index\n")
     file.write("      - Test Suite Name\n")
     file.write("      - Test Case Name\n")
@@ -98,24 +90,14 @@ def _update_line(file: TextIO, metadata: Dict[str, str], index: int) -> None:
         metadata (Dict[str, str]): test case metadata
         index (int): no.# of test case
     """
-    file.write("    * - " + str(index) + "\n")  # Index
+    file.write(f"    * - {index}\n")  # Index
     file.write(
-        "      - "
-        + ":ref:`"
-        + metadata["suite_name"]
-        + " <"
-        + metadata["suite_name"]
-        + ">`\n"
+        f"      - :ref:`{metadata['suite_name']} <{metadata['suite_name']}>`\n"
     )  # Test Suite Name
     file.write(
-        "      - "
-        + ":ref:`"
-        + metadata["case_name"]
-        + " <"
-        + metadata["case_name"]
-        + ">`\n"
+        f"      - :ref:`{metadata['case_name']} <{metadata['case_name']}>`\n"
     )  # Test Case Name
-    file.write("      - " + str(metadata.get("priority", 2)) + "\n")  # Priority
-    file.write("      - " + "Azure, Ready" + "\n")  # Platform - defaults to both
-    file.write("      - " + metadata["category"] + "\n")  # Category
-    file.write("      - " + metadata["area"] + "\n")  # Area
+    file.write(f"      - {metadata.get('priority', 2)}\n")  # Priority
+    file.write("      - Azure, Ready\n")  # Platform - defaults to both
+    file.write(f"      - {metadata['category']}\n")  # Category
+    file.write(f"      - {metadata['area']}\n")  # Area