docs: generate table containing all tests

Signed-off-by: Milosz Wasilewski <milosz.wasilewski@linaro.org>

4 files changed, 139 insertions, 19 deletions

diff --git a/docs/index.md b/docs/index.md
index abab38fd..44651eae 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -85,6 +85,36 @@ from all tests and save them to `${OUTPUT}/results.{json,csv}`. e.g.
 
     /root/output/result.json
 
+## Generating documentation
+
+[Full docs](https://test-definitions.readthedocs.io) are generated from existing
+YAML files. Resulting markdown files are not stored in the repository. In order
+to generate documentation locally one needs to follow the steps below:
+
+1. create and activate virtualenv  
+   ```
+   virtualenv -p python3 venv
+   source venv/bin/activate
+   ```
+2. install requirements  
+   ```
+   pip install -r mkdocs_plugin/requirements.txt
+   ```
+3. run mkdocs
+    * local http server  
+      ```
+      mkdocs serve
+      ```  
+      This will start small http server on http://127.0.0.1:8000
+
+    * build static docs  
+      ```
+      mkdocs build
+      ```  
+      This will convert all generated markdown files to HTML files. By default
+      files are stored in 'site' directory. See [mkdocs documentation](https://www.mkdocs.org/#building-the-site)
+      for more details.
+
 ## Contributing
 
 Please use Github for pull requests: https://github.com/Linaro/test-definitions/pulls
@@ -108,4 +138,4 @@ shell inside the container so that things like /root/output can be inspected.
 It is not (yet) a pass/fail test; merely a development helper and validation
 environment.
 
-For full documentation visit [mkdocs.org](https://mkdocs.org).
+For full documentation visit [test-definitions.readthedocs.io](https://test-definitions.readthedocs.io).
diff --git a/mkdocs.yml b/mkdocs.yml
index d2156604..bc1e96c9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,7 +5,11 @@ copyright: Linaro Ltd.
 theme:
     name: material
 plugins:
-    - linaro-test-definitions
+    - linaro-test-definitions:
+        table_dirs:
+            - 'automated/linux'
+            - 'automated/android'
+            - 'manual'
     - tags
     - exclude:
         glob:
diff --git a/mkdocs_plugin/setup.py b/mkdocs_plugin/setup.py
index 3ac025c3..e5094d27 100644
--- a/mkdocs_plugin/setup.py
+++ b/mkdocs_plugin/setup.py
@@ -3,7 +3,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='mkdocs-test-definitions-plugin',
-    version='1.1.1',
+    version='1.2',
     description='An MkDocs plugin that converts LAVA test definitions to documentation',
     long_description='',
     keywords='mkdocs python markdown wiki',
@@ -13,7 +13,8 @@ setup(
     license='GPL',
     python_requires='>=3.5',
     install_requires=[
-        'mkdocs>=1.1'
+        'mkdocs>=1.1',
+        'tags-macros-plugin'
     ],
     classifiers=[
         'Development Status :: 5 - Production/Stable',
diff --git a/mkdocs_plugin/testdefinitionsmkdocs/__init__.py b/mkdocs_plugin/testdefinitionsmkdocs/__init__.py
index f92f4fcd..20cfb005 100644
--- a/mkdocs_plugin/testdefinitionsmkdocs/__init__.py
+++ b/mkdocs_plugin/testdefinitionsmkdocs/__init__.py
@@ -5,16 +5,40 @@ import yaml
 
 from mkdocs.plugins import BasePlugin
 from mkdocs.structure.files import File
+from mkdocs.config.config_options import Type
 from mdutils.fileutils.fileutils import MarkDownFile
 
 
 class LinaroTestDefinitionsMkDocsPlugin(BasePlugin):
+
+    config_scheme = (
+        ("table_file", Type(str, default="tests_table")),
+        ("table_dirs", Type(list, default=["automated", "manual"])),
+    )
+
+    def __init__(self):
+        self.table_dirs = ["automated", "manual"]
+        self.table_filename = "tests_table"
+        self.test_tables = {}
+
+    def on_config(self, config, **kwargs):
+        self.table_filename = self.config.get("table_file", self.table_filename)
+        self.table_dirs = self.config.get("table_dirs", self.table_dirs)
+        for name in self.table_dirs:
+            self.test_tables[name] = []
+
+    def __add_list_with_header(self, mdFile, header_string, item_list):
+        mdFile.new_header(level=2, title=header_string)
+        if item_list is not None:
+            for item in item_list:
+                mdFile.new_line(" * %s" % item)
+
     def generate_yaml_markdown(self, filename, config):
         # remove leading ./
         new_filename = filename.split("/", 1)[1]
         # remove .yaml
         new_filename = new_filename.rsplit(".", 1)[0]
-        tmp_filename = os.path.join(config['docs_dir'], new_filename)
+        tmp_filename = os.path.join(config["docs_dir"], new_filename)
         filecontent = None
         try:
             with open(filename, "r") as f:
@@ -25,34 +49,66 @@ class LinaroTestDefinitionsMkDocsPlugin(BasePlugin):
             content = yaml.load(filecontent, Loader=yaml.Loader)
             if "metadata" in content.keys():
                 metadata = content["metadata"]
-                mdFile = mdutils.MdUtils(file_name=tmp_filename, title=metadata['name'])
+                mdFile = mdutils.MdUtils(file_name=tmp_filename)
                 tags_section = "---\n"
-                tags_section += "title: %s\n" % metadata['name']
+                tags_section += "title: %s\n" % metadata["name"]
                 tags_section += "tags:\n"
-                scope_list = metadata.get("scope", None)
+                scope_list = metadata.get("scope", [])
+                os_list = metadata.get("os", [])
+                device_list = metadata.get("devices", [])
                 if scope_list is not None:
                     for item in scope_list:
                         tags_section += " - %s\n" % item
                 tags_section += "---\n"
-                mdFile.new_header(level=1, title="Test name: %s" % metadata['name'])
-                mdFile.new_header(level=1, title="Description")
-                mdFile.new_paragraph(metadata['description'])
-                mdFile.new_header(level=1, title="Maintainer")
+                mdFile.new_header(level=1, title=new_filename)
+                mdFile.new_header(level=2, title="Description")
+                mdFile.write(metadata["description"])
+                mdFile.new_header(level=2, title="Maintainer")
                 maintainer_list = metadata.get("maintainer", None)
                 if maintainer_list is not None:
                     for item in maintainer_list:
                         mdFile.new_line(" * %s" % item)
-                mdFile.new_header(level=1, title="Scope")
-                if scope_list is not None:
-                    for item in scope_list:
-                        mdFile.new_line(" * %s" % item)
+                self.__add_list_with_header(mdFile, "OS", os_list)
+                self.__add_list_with_header(mdFile, "Scope", scope_list)
+                self.__add_list_with_header(mdFile, "Devices", device_list)
+                mdFile.new_header(level=2, title="Steps to reproduce")
+                steps_list = content["run"]["steps"]
+                for line in steps_list:
+                    bullet_string = " * "
+                    if str(line).startswith("#"):
+                        bullet_string = " * \\"
+                    mdFile.new_line(bullet_string + str(line))
                 try:
                     os.makedirs(os.path.dirname(tmp_filename))
                 except OSError as exc:  # Guard against race condition
                     if exc.errno != errno.EEXIST:
                         raise
                 md_file = MarkDownFile(mdFile.file_name)
-                md_file.rewrite_all_file(data=tags_section + mdFile.title + mdFile.table_of_contents + mdFile.file_data_text)
+                md_file.rewrite_all_file(
+                    data=tags_section
+                    + mdFile.title
+                    + mdFile.table_of_contents
+                    + mdFile.file_data_text
+                )
+                # add row to tests_table
+                table_key = None
+                for table_name in self.table_dirs:
+                    if new_filename.startswith(table_name):
+                        table_key = table_name
+                if table_key is not None:
+                    self.test_tables[table_key].append(
+                        {
+                            "name": "[%s](%s.md)" % (metadata["name"], new_filename),
+                            "description": metadata["description"],
+                            "scope": ", ".join(
+                                [
+                                    "[%s](tags.md#%s)"
+                                    % (x, x.lower().replace(" ", "-").replace("/", ""))
+                                    for x in scope_list
+                                ]
+                            ),
+                        }
+                    )
                 return new_filename + ".md"
         except yaml.YAMLError:
             return None
@@ -64,8 +120,37 @@ class LinaroTestDefinitionsMkDocsPlugin(BasePlugin):
             for filename in filenames:
                 if filename.endswith(".yaml"):
                     new_filename = os.path.join(root, filename)
-                    markdown_filename = self.generate_yaml_markdown(new_filename, config)
+                    markdown_filename = self.generate_yaml_markdown(
+                        new_filename, config
+                    )
                     if markdown_filename is not None:
-                        f = File(markdown_filename, config['docs_dir'], config['site_dir'], False)
+                        f = File(
+                            markdown_filename,
+                            config["docs_dir"],
+                            config["site_dir"],
+                            False,
+                        )
                         files.append(f)
+        mdFile = mdutils.MdUtils(
+            file_name=config["docs_dir"] + "/" + self.table_filename
+        )
+        mdFile.new_header(level=1, title="Tests index")
+        for table_name, test_table in self.test_tables.items():
+            mdFile.new_header(level=2, title='<span class="tag">%s</span>' % table_name)
+            mdFile.new_line("| Name | Description | Scope |")
+            mdFile.new_line("| --- | --- | --- |")
+            for row in sorted(test_table, key=lambda item: item["name"]):
+                mdFile.new_line(
+                    "| %s | %s | %s |"
+                    % (row["name"], row["description"].replace("\n", ""), row["scope"])
+                )
+            mdFile.new_line("")
+        mdFile.create_md_file()
+        newfile = File(
+            path=str(self.table_filename) + ".md",
+            src_dir=config["docs_dir"],
+            dest_dir=config["site_dir"],
+            use_directory_urls=False,
+        )
+        files.append(newfile)
         return files