Re: [PATCH i-g-t v2 3/3] tests/intel: Put "Run type" highest in i915 documentation hierarchy

[Mauro Carvalho Chehab <mauro.chehab@linux.intel.com>]

On Tue, 23 Apr 2024 09:53:44 +0000
Katarzyna Piecielska <katarzyna.piecielska@intel.com> wrote:

> Let's put "Run type" at highest place in i915 documentation hierarchy. It
> will be reflected in html generated documentation.
> 
> Signed-off-by: Katarzyna Piecielska <katarzyna.piecielska@intel.com>
> Cc: Kamil Konieczny <kamil.konieczny@intel.com>
> Cc: Jari Tahvanainen <jari.tahvanainen@intel.com>
> Cc: Mauro Carvalho Chehab <mauro.chehab@linux.intel.com>
> ---
>  tests/intel/i915_test_config.json | 150 +++++++++++++++---------------
>  1 file changed, 75 insertions(+), 75 deletions(-)
> 
> diff --git a/tests/intel/i915_test_config.json b/tests/intel/i915_test_config.json
> index 61638a4f1..7b4e11ab5 100644
> --- a/tests/intel/i915_test_config.json
> +++ b/tests/intel/i915_test_config.json

JSON file doesn't look right as it places all fields inside the
hierarchical part below Run Type, including fields that should be
outside, like Description.

Also, it is using tabs (meaning 4 spaces) instead of just
whitespaces, causing bad indentation with tabs convention for the
Kernel and IGT (tab = 8 spaces).

What about using instead:

{
    "description": "JSON file to be used to parse i915 documentation",
    "name": "Tests for i915 Driver",
    "drivers": [ "i915" ],
    "files": [ "*.c", "../core_auth.c", "../core_getclient.c",
               "../core_getstats.c", "../core_getversion.c",
               "../core_hotunplug.c", "../core_setmaster.c",
               "../core_setmaster_vs_auth.c", "../debugfs_test.c",
               "../device_reset.c", "../dmabuf.c",
               "../drm_import_export.c", "../drm_mm.c",
               "../dumb_buffer.c", "../prime_busy.c", "../prime_mmap.c",
               "../prime_mmap_coherency.c", "../prime_self_import.c",
               "../prime_vgem.c", "../sw_sync.c", "../syncobj_basic.c",
               "../syncobj_timeline.c", "../syncobj_wait.c",
               "../vgem_basic.c", "../vgem_slow.c" ],
    "exclude_files": [ "kms_*", "gem_concurrent_all.c", "gem_concurrent_blit.c",
                       "xe_*" ],
    "fields": {
        "Run type": {
            "_properties_": {
                "mandatory": true,
                "description": "Defines what category of testlist it belongs",
                "default-testlist": "FULL",
                "update-from-file": {
                    "exclude-type": "regex-ignorecase",
                    "append-value-if-not-excluded": "i915 FULL",
                    "include": [
                        { "i915 BAT": "../intel-ci/fast-feedback.testlist" }
                    ],
                    "exclude": [
                        { "all": "../intel-ci/blacklist.txt" }
                    ]
                },
                "order": [
                    "boot",
                    "__all__",
                    "kunit"
                ]
            },
            "Category": {
                "_properties_": {
                    "mandatory": true,
                    "description": "Contains the major group for the tested functionality, being hardware, software or firmware"
                },
                "Mega feature": {
                    "_properties_": {
                        "description": "Contains the mega feature for end to end use case, e. g. the 'sellable' feature."
                    },
                    "Sub-category": {
                        "_properties_": {
                            "mandatory": true,
                            "description": "Contains the technical feature/functionality"
                        },
                        "Functionality": {
                            "_properties_": {
                                "mandatory": true,
                                "description": "Groups page table tests on buckets containg more detailed functionality"
                            },
                            "Feature": {
                                "_properties_": {
                                    "description": "Describes the lowest level feature bucket"
                                }
                            }
                        }
                    }
                }
            }
        },
        "Test category": {
            "_properties_": {
                "description": "Defines the test category. Usually used at subtest level."
            }
        },
        "Test requirement": {
            "_properties_": {
                "description": "Defines Kernel parameters required for the test to run"
            }
        },
        "Issue": {
            "_properties_": {
                "description": "If the test is used to solve an issue, point to the URL containing the issue."
            }
        },
        "GPU excluded platform": {
            "_properties_": {
                "description": "Provides a list of GPUs not capable of running the subtest (or the test as a whole)."
            }
        },
        "GPU requirement": {
            "_properties_": {
                "description": "Describes any GPU-specific requrirement, like requiring multi-tiles."
            }
        },
        "Depends on" : {
            "_properties_": {
                "description": "List other subtests that are required to not be skipped before calling this one."
            }
        },
        "TODO": {
            "_properties_": {
                "description": "Point to known missing features at the test or subtest."
            }
        },
        "Description" : {
            "_properties_": {
                "description": "Provides a description for the test/subtest."
            }
        }
    }
}