[LTP] [PATCH v2] doc: add tests catalog page
Andrea Cervesato
andrea.cervesato@suse.de
Tue Feb 4 15:24:32 CET 2025
From: Andrea Cervesato <andrea.cervesato@suse.com>
Add a new section in the LTP documentation website, where we list all
tests which are available in LTP and supporting new API.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
This patch-set is meant to introduce a new page in the LTP
documentation, showing tests which are currently available with their
description and information.
---
Changes in v2:
- add setup
- cleanup code
- Link to v1: https://lore.kernel.org/r/20250203-doc_tests_list-v1-1-5fe69c07b1ab@suse.com
---
doc/.gitignore | 1 +
doc/conf.py | 264 ++++++++++++++++++++++++++++++++++++++++++++-
doc/index.rst | 4 +
doc/users/test_catalog.rst | 7 ++
4 files changed, 272 insertions(+), 4 deletions(-)
diff --git a/doc/.gitignore b/doc/.gitignore
index 173179852070f25acb6a729975df9d52d171b422..2b05a1ec368573778cfe7ee6a1cb5d6c5ecb0b5a 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,4 +1,5 @@
html/
build/
_static/syscalls.rst
+_static/tests.rst
syscalls.tbl
diff --git a/doc/conf.py b/doc/conf.py
index c6a84ea5810424ce6e1c21d81946c1819f10a3cc..4a9823038e7fa335de46a6531ccd1468c9ad16c8 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -5,6 +5,7 @@
import os
import re
+import json
import socket
import urllib.request
import sphinx
@@ -17,6 +18,7 @@ copyright = '2024, Linux Test Project'
author = 'Linux Test Project'
release = '1.0'
ltp_repo = 'https://github.com/linux-test-project/ltp'
+ltp_repo_base_url = f"{ltp_repo}/tree/master"
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -25,7 +27,7 @@ extensions = [
'linuxdoc.rstKernelDoc',
'sphinxcontrib.spelling',
'sphinx.ext.autosectionlabel',
- 'sphinx.ext.extlinks'
+ 'sphinx.ext.extlinks',
]
exclude_patterns = ["html*", '_static*']
@@ -138,7 +140,6 @@ def generate_syscalls_stats(_):
if error:
return
- syscalls_base_url = f"{ltp_repo}/tree/master"
text = [
'Syscalls\n',
'--------\n\n',
@@ -176,7 +177,7 @@ def generate_syscalls_stats(_):
path = dirpath.replace('../', '')
name = match.group('name')
- ltp_syscalls[name] = f'{syscalls_base_url}/{path}'
+ ltp_syscalls[name] = f'{ltp_repo_base_url}/{path}'
# compare kernel syscalls with LTP tested syscalls
syscalls = {}
@@ -186,7 +187,7 @@ def generate_syscalls_stats(_):
if kersc not in syscalls:
if kersc in white_list:
- syscalls[kersc] = f'{syscalls_base_url}/{white_list[kersc]}'
+ syscalls[kersc] = f'{ltp_repo_base_url}/{white_list[kersc]}'
continue
syscalls[kersc] = None
@@ -208,6 +209,7 @@ def generate_syscalls_stats(_):
'Tested syscalls\n',
'~~~~~~~~~~~~~~~\n\n',
'.. list-table::\n',
+ ' :widths: 25, 25'
' :header-rows: 0\n\n',
]
@@ -216,6 +218,7 @@ def generate_syscalls_stats(_):
'Untested syscalls\n',
'~~~~~~~~~~~~~~~~~\n\n',
'.. list-table::\n',
+ ' :widths: 25, 25'
' :header-rows: 0\n\n',
]
@@ -256,6 +259,258 @@ def generate_syscalls_stats(_):
stats.writelines(text)
+def _generate_tags_table(tags):
+ """
+ Generate the tags table from tags hash.
+ """
+ supported_url_ref = {
+ "linux-git": "https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=",
+ "linux-stable-git": "https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/?id=",
+ "glibc-git": "https://sourceware.org/git/?p=glibc.git;a=commit;h=",
+ "musl-git": "https://git.musl-libc.org/cgit/musl/commit/src/linux/clone.c?id=",
+ "CVE": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-",
+ }
+
+ table = [
+ '.. list-table::',
+ ' :widths: 25, 25'
+ ' :header-rows: 1',
+ '',
+ ' * - Tag',
+ ' - Info',
+ ]
+
+ for tag in tags:
+ tag_key = tag[0]
+ tag_val = tag[1]
+
+ tag_url = supported_url_ref.get(tag_key, None)
+ if tag_url:
+ tag_val = f'`{tag_val} <{tag_url}{tag_val}>`_'
+
+ table.extend([
+ f' * - {tag_key}',
+ f' - {tag_val}',
+ ])
+
+ return table
+
+
+def _generate_options_table(options):
+ """
+ Generate the options table from the options hash.
+ """
+ table = [
+ '.. list-table::',
+ ' :header-rows: 1',
+ '',
+ ' * - Option',
+ ' - Description',
+ ]
+
+ for opt in options:
+ if not isinstance(opt, list):
+ table.clear()
+ break
+
+ key = opt[0]
+ val = opt[2]
+
+ if key.endswith(':'):
+ key = key[:-1] if key.endswith(':') else key
+
+ key = f'-{key}'
+
+ table.extend([
+ f' * - {key}',
+ f' - {val}',
+ ])
+
+ return table
+
+
+def _generate_setup_table(keys):
+ """
+ Generate the table with test setup configuration.
+ """
+ exclude = [
+ 'child_needs_reinit',
+ 'needs_checkpoints',
+ 'resource_files',
+ 'save_restore',
+ 'forks_child',
+ 'hugepages',
+ 'options',
+ 'timeout',
+ 'ulimit',
+ 'fname',
+ 'tags',
+ 'doc',
+ ]
+ my_keys = {k: v for k, v in keys.items() if k not in exclude}
+ if len(my_keys) == 0:
+ return []
+
+ table = [
+ '.. list-table::',
+ ' :header-rows: 1',
+ '',
+ ' * - Key',
+ ' - Value',
+ ]
+
+ keys_list = [
+ 'needs_cgroup_ctrls',
+ 'skip_filesystems',
+ 'supported_archs',
+ 'needs_kconfigs',
+ 'needs_drivers',
+ 'needs_cmds',
+ 'caps',
+ ]
+
+ for key, value in my_keys.items():
+ if key in exclude:
+ continue
+
+ if key in keys_list:
+ if len(value) > 1:
+ table.extend([
+ f' * - {key}',
+ f' - | {value[0]}',
+ ])
+
+ for item in value[1:]:
+ table.append(f' | {item}')
+ else:
+ table.extend([
+ f' * - {key}',
+ f' - {value[0]}',
+ ])
+ elif key == 'filesystems':
+ values = []
+ for v in value:
+ for item in v:
+ if isinstance(item, list):
+ continue
+
+ if item.startswith('.type'):
+ values.append(item.replace('.type=', ''))
+
+ if len(values) > 1:
+ table.extend([
+ f' * - {key}',
+ f' - | {values[0]}',
+ ])
+
+ for item in values[1:]:
+ table.append(f' | {item}')
+ else:
+ table.extend([
+ f' * - {key}',
+ f' - {values[0]}',
+ ])
+ else:
+ table.extend([
+ f' * - {key}',
+ f' - {value}'
+ ])
+
+ return table
+
+
+def generate_test_catalog(_):
+ """
+ Generate the test catalog from ltp.json metadata file.
+ """
+ output = '_static/tests.rst'
+ metadata_file = '../metadata/ltp.json'
+ text = []
+
+ metadata = None
+ with open(metadata_file, 'r', encoding='utf-8') as data:
+ metadata = json.load(data)
+
+ timeout_def = metadata['defaults']['timeout']
+
+ for test_name, conf in metadata['tests'].items():
+ text.extend([
+ f'{test_name}',
+ len(test_name) * '-'
+ ])
+
+ # source url location
+ test_fname = conf.get('fname', None)
+ if test_fname:
+ text.extend([
+ '',
+ f"`source <{ltp_repo_base_url}/{test_fname}>`__",
+ ''
+ ])
+
+ # test description
+ desc = conf.get('doc', None)
+ if desc:
+ desc_text = []
+ for line in desc:
+ if line.startswith("[Description]"):
+ desc_text.append("**Description**")
+ elif line.startswith("[Algorithm]"):
+ desc_text.append("**Algorithm**")
+ else:
+ desc_text.append(line)
+
+ text.extend([
+ '\n'.join(desc_text),
+ ])
+
+ # timeout information
+ timeout = conf.get('timeout', None)
+ if timeout:
+ text.extend([
+ '',
+ f'Test timeout to {timeout} seconds.',
+ ''
+ ])
+ else:
+ text.extend([
+ '',
+ f'Test timeout defaults to {timeout_def} seconds.',
+ ''
+ ])
+
+ # options information
+ opts = conf.get('options', None)
+ if opts:
+ text.append('')
+ text.extend(_generate_options_table(opts))
+ text.append('')
+
+ # tags information
+ tags = conf.get('tags', None)
+ if tags:
+ text.append('')
+ text.extend(_generate_tags_table(tags))
+ text.append('')
+
+ # developer information
+ text.append('')
+ text.extend(_generate_setup_table(conf))
+ text.append('')
+
+ # small separator between tests
+ text.extend([
+ '',
+ '.. raw:: html',
+ '',
+ ' <hr>',
+ '',
+ ])
+
+ with open(output, 'w+', encoding='utf-8') as new_tests:
+ new_tests.write('\n'.join(text))
+
+
def setup(app):
"""
Setup the current documentation, using self generated data and graphics
@@ -263,3 +518,4 @@ def setup(app):
"""
app.add_css_file('custom.css')
app.connect('builder-inited', generate_syscalls_stats)
+ app.connect('builder-inited', generate_test_catalog)
diff --git a/doc/index.rst b/doc/index.rst
index b907ac36f0c9328c576d25dee5777d808c2e5119..c00a59d31345142e78deb74eacc9da2941291d76 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,7 @@
users/setup_tests
users/supported_systems
users/stats
+ users/test_catalog
.. toctree::
:maxdepth: 3
@@ -54,6 +55,9 @@ For users
:doc:`users/stats`
Some LTP statistics
+:doc:`users/test_catalog`
+ The LTP test catalog
+
For developers
--------------
diff --git a/doc/users/test_catalog.rst b/doc/users/test_catalog.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b1674f9dc614ea04a89cf084e92b72c6862a5f48
--- /dev/null
+++ b/doc/users/test_catalog.rst
@@ -0,0 +1,7 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Test catalog
+============
+
+.. include:: ../_static/tests.rst
+
---
base-commit: 0f38cb8e8ea8097620eee0ba79e5e321f8a898bb
change-id: 20250131-doc_tests_list-1b82f51e43fd
Best regards,
--
Andrea Cervesato <andrea.cervesato@suse.com>
More information about the ltp
mailing list