* [LTP] [PATCH v3] doc: add tests catalog page
@ 2025-02-05 12:32 Andrea Cervesato
2025-02-05 15:26 ` Cyril Hrubis
0 siblings, 1 reply; 3+ messages in thread
From: Andrea Cervesato @ 2025-02-05 12:32 UTC (permalink / raw)
To: ltp
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 v3:
- fix table widths alignment
- add warning at the beginning of the test catalog
- Link to v2: https://lore.kernel.org/r/20250204-doc_tests_list-v2-1-9d29aeacc3f3@suse.com
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 | 267 ++++++++++++++++++++++++++++++++++++++++++++-
doc/index.rst | 4 +
doc/users/test_catalog.rst | 7 ++
4 files changed, 275 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..9dc03933185b547df967f144104b6771d84ff3bd 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
@@ -256,6 +257,263 @@ 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::',
+ ' :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 = [
+ '.. warning::',
+ ' The following catalog has been generated using LTP metadata',
+ ' which is including only tests using the new :ref:`LTP C API`.',
+ ' For this reason, some old tests might be missing from the list.',
+ ''
+ ]
+
+ 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 +521,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: 07d79673a65f0f5f06c19507df4a15ceab22f2f9
change-id: 20250131-doc_tests_list-1b82f51e43fd
Best regards,
--
Andrea Cervesato <andrea.cervesato@suse.com>
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply related [flat|nested] 3+ messages in thread* Re: [LTP] [PATCH v3] doc: add tests catalog page
2025-02-05 12:32 [LTP] [PATCH v3] doc: add tests catalog page Andrea Cervesato
@ 2025-02-05 15:26 ` Cyril Hrubis
2025-02-05 15:42 ` Andrea Cervesato via ltp
0 siblings, 1 reply; 3+ messages in thread
From: Cyril Hrubis @ 2025-02-05 15:26 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: ltp
Hi!
> + # timeout information
> + timeout = conf.get('timeout', None)
> + if timeout:
> + text.extend([
> + '',
> + f'Test timeout to {timeout} seconds.',
^
is
> + ''
> + ])
> + else:
> + text.extend([
> + '',
> + f'Test timeout defaults to {timeout_def} seconds.',
> + ''
> + ])
Maybe it would make sense to add runtime here as well since it's
logically connected to the timeout.
Otherwise:
Acked-by: Cyril Hrubis <chrubis@suse.cz>
--
Cyril Hrubis
chrubis@suse.cz
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 3+ messages in thread* Re: [LTP] [PATCH v3] doc: add tests catalog page
2025-02-05 15:26 ` Cyril Hrubis
@ 2025-02-05 15:42 ` Andrea Cervesato via ltp
0 siblings, 0 replies; 3+ messages in thread
From: Andrea Cervesato via ltp @ 2025-02-05 15:42 UTC (permalink / raw)
To: Cyril Hrubis, Andrea Cervesato; +Cc: ltp
Hi!
On 2/5/25 16:26, Cyril Hrubis wrote:
> Hi!
>> + # timeout information
>> + timeout = conf.get('timeout', None)
>> + if timeout:
>> + text.extend([
>> + '',
>> + f'Test timeout to {timeout} seconds.',
> ^
> is
>> + ''
>> + ])
>> + else:
>> + text.extend([
>> + '',
>> + f'Test timeout defaults to {timeout_def} seconds.',
>> + ''
>> + ])
> Maybe it would make sense to add runtime here as well since it's
> logically connected to the timeout.
Probably yes. I will add it and correct the text.
>
> Otherwise:
>
> Acked-by: Cyril Hrubis <chrubis@suse.cz>
>
Andrea
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2025-02-05 15:42 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-02-05 12:32 [LTP] [PATCH v3] doc: add tests catalog page Andrea Cervesato
2025-02-05 15:26 ` Cyril Hrubis
2025-02-05 15:42 ` Andrea Cervesato via ltp
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.