diff --git a/docs/conf.py b/docs/conf.py index 2d195c6697..4e26475e7a 100644 --- a/docs/conf.py +++ b/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"] diff --git a/docs/installation_linux.rst b/docs/installation_linux.rst index 4bffb34f9d..ee0d1adfde 100644 --- a/docs/installation_linux.rst +++ b/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 diff --git a/docs/tools/test_spec_gen.py b/docs/tools/test_spec_gen.py index 3fc2b716b0..55ffcd6851 100644 --- a/docs/tools/test_spec_gen.py +++ b/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") diff --git a/docs/tools/test_summary_gen.py b/docs/tools/test_summary_gen.py index a22a7ba878..9c4bcb0ff7 100644 --- a/docs/tools/test_summary_gen.py +++ b/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