| Message ID | 20240425222331.315701-1-pvorel@suse.cz |
|---|---|
| State | Accepted |
| Headers | show |
| Series | [1/1] doc: Link file/directory names to GitHub sources | expand |
Hi! Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com> On 4/26/24 00:23, Petr Vorel wrote: > Convert all the files/directory names which actually points to real > files/directories to the links to GitHub sources. Exception is > datafiles/Makefile and some examples. > > For now we use link to the master, maybe we want to change that if we > ever generate stable docs. > > Signed-off-by: Petr Vorel <pvorel@suse.cz> > --- > doc/conf.py | 2 +- > doc/developers/test_case_tutorial.rst | 18 +++++++++--------- > doc/developers/writing_tests.rst | 22 +++++++++++----------- > doc/users/quick_start.rst | 2 +- > 4 files changed, 22 insertions(+), 22 deletions(-) > > diff --git a/doc/conf.py b/doc/conf.py > index d0f185b28..80f6df99b 100644 > --- a/doc/conf.py > +++ b/doc/conf.py > @@ -162,7 +162,7 @@ def generate_syscalls_stats(_): > > # generate the statistics file > tested_syscalls = [key for key, val in syscalls.items() if val] > - text.append('syscalls which are tested under **testcases/kernel/syscalls**:\n\n') > + text.append('syscalls which are tested under :master:`testcases/kernel/syscalls`:\n\n') > text.append(f'* kernel syscalls: {len(ker_syscalls)}\n') > text.append(f'* tested syscalls: {len(tested_syscalls)}\n\n') > > diff --git a/doc/developers/test_case_tutorial.rst b/doc/developers/test_case_tutorial.rst > index 6ec618b9b..6c38fdbf1 100644 > --- a/doc/developers/test_case_tutorial.rst > +++ b/doc/developers/test_case_tutorial.rst > @@ -56,7 +56,7 @@ test. At the time of writing there is no test for this call which was > introduced in Linux kernel version 4.11. > > Linux system call specific tests are primarily contained in > -``testcases/kernel/syscalls``, but you should also ``git grep`` the entire LTP > +:master:`testcases/kernel/syscalls`, but you should also ``git grep`` the entire LTP > repository to check for any existing usages of a system call. > > One way to find a system call which is not currently tested by the LTP is to > @@ -195,7 +195,7 @@ following line after ``testcases.mk``. > > statx01: CFLAGS += -pthread > > -Assuming you are in the test's subdirectory ``testcases/kernel/syscalls/statx``, > +Assuming you are in the test's subdirectory :master:`testcases/kernel/syscalls/statx`, > please do: > > .. code-block:: bash > @@ -204,10 +204,10 @@ please do: > ./statx01 > > This should build the test and then run it. However, even though the test is > -in the ``syscalls`` directory it won't be automatically ran as part of the > -syscalls test group (e.g. ``./runltp -f syscalls``). > -For this we need to add it to the ``runtest`` file. So open > -``runtest/syscalls`` and add the lines starting with a ``+``. > +in :master:`testcases/kernel/syscalls/` directory it won't be automatically ran > +as part of the syscalls test group (e.g. not run via ``kirk -r math`` or > +``./runltp -f syscalls``). For this we need to add it to the runtest file. So > +open :master:`runtest/syscalls` and add the lines starting with a ``+``. > > .. code-block:: > > @@ -219,9 +219,9 @@ For this we need to add it to the ``runtest`` file. So open > stime01 stime01 > stime02 stime02 > > -The ``runtest`` files are in a two column format. The first column is the test > -name, which is mainly used by test runners for reporting and filtering. It is > -just a single string of text with no spaces. The second column, which can > +The :master:`runtest` files are in a two column format. The first column is the > +test name, which is mainly used by test runners for reporting and filtering. It > +is just a single string of text with no spaces. The second column, which can > contain spaces, is passed to the shell in order to execute the test. Often it > is just the executable name, but some tests also take arguments (the LTP has a > library for argument parsing, by the way). > diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst > index daaa4b9f8..85a7a1d8a 100644 > --- a/doc/developers/writing_tests.rst > +++ b/doc/developers/writing_tests.rst > @@ -211,7 +211,7 @@ There are several types of checks we use: > > * Sometimes it makes sense to define a few macros instead of creating a > configure test. One example is Linux specific POSIX clock ids in > - ``include/lapi/posix_clocks.h`` > + :master:`include/lapi/posix_clocks.h`. > > Dealing with messed up legacy code > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > @@ -242,11 +242,11 @@ portable shell or C. The test gets a configuration via environment variables > and/or command line parameters, it prints additional information into the > stdout and reports overall success/failure via the exit value. > > -Tests are generally placed under the ``testcases/`` directory. Everything that > +Tests are generally placed under the :master:`testcases/` directory. Everything that > is a syscall or (slightly confusingly) libc syscall wrapper, goes under > -``testcases/kernel/syscalls/``. > +:master:`testcases/kernel/syscalls/`. > > -There is also ``testcases/open_posix_testsuite/`` which is a well maintained > +There is also :master:`testcases/open_posix_testsuite/` which is a well maintained > fork of the Open POSIX testsuite project, that has been dead since 2005. > > We also have a number of directories with tests for more specific features, such > @@ -256,8 +256,8 @@ Runtest Files > ~~~~~~~~~~~~~ > > The list of tests to be executed is stored in runtest files under the > -``runtest/`` directory. The default set of runtest files to be executed is > -stored in ``scenario_groups/default``. When you add a test, you should add > +:master:`runtest/` directory. The default set of runtest files to be executed is > +stored in :master:`scenario_groups/default`. When you add a test, you should add > corresponding entries into some runtest file(s) as well. > > Each line of runtest file contains one test. The first item is the test name. > @@ -270,9 +270,9 @@ All other items, separated by space will be executed as a command. > > Blank lines and lines starting with a ``#`` (comments) are ignored. > > -Syscalls tests, placed under ``testcases/kernel/syscalls/``, use > -``runtest/syscalls`` file. For kernel related tests for memory management we > -have ``runtest/mm``, etc. > +Syscalls tests, placed under :master:`testcases/kernel/syscalls/`, use > +:master:`runtest/syscalls` file. For kernel related tests for memory management we > +have :master:`runtest/mm`, etc. > > .. note:: > > @@ -286,7 +286,7 @@ Datafiles > If your test needs data files, these should be put into a subdirectory > named ``datafiles`` and installed into the ``testcases/data/$TCID`` directory. > This will require to add ``INSTALL_DIR := testcases/data/TCID`` into > -``datafiles/Makefile``. > +correspondent ``datafiles/Makefile``. > > You can obtain path to datafiles via ``$TST_DATAROOT`` provided by ``test.sh`` > or via C function ``tst_dataroot()`` provided by libltp: > @@ -337,7 +337,7 @@ Testing pre-release kernel features > ----------------------------------- > > Tests for features not yet in the mainline kernel release are accepted. However, > -they must be added only to the **staging** runtest file. Once a feature is part > +they must be added only to :master:`runtest/staging`. Once a feature is part > of the stable kernel ABI, the associated test must be moved out of staging. > > Testing builds with GitHub Actions > diff --git a/doc/users/quick_start.rst b/doc/users/quick_start.rst > index 69792999b..4a48745be 100644 > --- a/doc/users/quick_start.rst > +++ b/doc/users/quick_start.rst > @@ -123,4 +123,4 @@ Network tests > ------------- > > Network tests usually require a certain setup that is described in > -``testcases/network/README.md``. > +:master:`testcases/network/README.md`.
Hi Andrea, > Hi! > Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com> Thanks for your review, merged! Kind regards, Petr
diff --git a/doc/conf.py b/doc/conf.py index d0f185b28..80f6df99b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -162,7 +162,7 @@ def generate_syscalls_stats(_): # generate the statistics file tested_syscalls = [key for key, val in syscalls.items() if val] - text.append('syscalls which are tested under **testcases/kernel/syscalls**:\n\n') + text.append('syscalls which are tested under :master:`testcases/kernel/syscalls`:\n\n') text.append(f'* kernel syscalls: {len(ker_syscalls)}\n') text.append(f'* tested syscalls: {len(tested_syscalls)}\n\n') diff --git a/doc/developers/test_case_tutorial.rst b/doc/developers/test_case_tutorial.rst index 6ec618b9b..6c38fdbf1 100644 --- a/doc/developers/test_case_tutorial.rst +++ b/doc/developers/test_case_tutorial.rst @@ -56,7 +56,7 @@ test. At the time of writing there is no test for this call which was introduced in Linux kernel version 4.11. Linux system call specific tests are primarily contained in -``testcases/kernel/syscalls``, but you should also ``git grep`` the entire LTP +:master:`testcases/kernel/syscalls`, but you should also ``git grep`` the entire LTP repository to check for any existing usages of a system call. One way to find a system call which is not currently tested by the LTP is to @@ -195,7 +195,7 @@ following line after ``testcases.mk``. statx01: CFLAGS += -pthread -Assuming you are in the test's subdirectory ``testcases/kernel/syscalls/statx``, +Assuming you are in the test's subdirectory :master:`testcases/kernel/syscalls/statx`, please do: .. code-block:: bash @@ -204,10 +204,10 @@ please do: ./statx01 This should build the test and then run it. However, even though the test is -in the ``syscalls`` directory it won't be automatically ran as part of the -syscalls test group (e.g. ``./runltp -f syscalls``). -For this we need to add it to the ``runtest`` file. So open -``runtest/syscalls`` and add the lines starting with a ``+``. +in :master:`testcases/kernel/syscalls/` directory it won't be automatically ran +as part of the syscalls test group (e.g. not run via ``kirk -r math`` or +``./runltp -f syscalls``). For this we need to add it to the runtest file. So +open :master:`runtest/syscalls` and add the lines starting with a ``+``. .. code-block:: @@ -219,9 +219,9 @@ For this we need to add it to the ``runtest`` file. So open stime01 stime01 stime02 stime02 -The ``runtest`` files are in a two column format. The first column is the test -name, which is mainly used by test runners for reporting and filtering. It is -just a single string of text with no spaces. The second column, which can +The :master:`runtest` files are in a two column format. The first column is the +test name, which is mainly used by test runners for reporting and filtering. It +is just a single string of text with no spaces. The second column, which can contain spaces, is passed to the shell in order to execute the test. Often it is just the executable name, but some tests also take arguments (the LTP has a library for argument parsing, by the way). diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst index daaa4b9f8..85a7a1d8a 100644 --- a/doc/developers/writing_tests.rst +++ b/doc/developers/writing_tests.rst @@ -211,7 +211,7 @@ There are several types of checks we use: * Sometimes it makes sense to define a few macros instead of creating a configure test. One example is Linux specific POSIX clock ids in - ``include/lapi/posix_clocks.h`` + :master:`include/lapi/posix_clocks.h`. Dealing with messed up legacy code ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -242,11 +242,11 @@ portable shell or C. The test gets a configuration via environment variables and/or command line parameters, it prints additional information into the stdout and reports overall success/failure via the exit value. -Tests are generally placed under the ``testcases/`` directory. Everything that +Tests are generally placed under the :master:`testcases/` directory. Everything that is a syscall or (slightly confusingly) libc syscall wrapper, goes under -``testcases/kernel/syscalls/``. +:master:`testcases/kernel/syscalls/`. -There is also ``testcases/open_posix_testsuite/`` which is a well maintained +There is also :master:`testcases/open_posix_testsuite/` which is a well maintained fork of the Open POSIX testsuite project, that has been dead since 2005. We also have a number of directories with tests for more specific features, such @@ -256,8 +256,8 @@ Runtest Files ~~~~~~~~~~~~~ The list of tests to be executed is stored in runtest files under the -``runtest/`` directory. The default set of runtest files to be executed is -stored in ``scenario_groups/default``. When you add a test, you should add +:master:`runtest/` directory. The default set of runtest files to be executed is +stored in :master:`scenario_groups/default`. When you add a test, you should add corresponding entries into some runtest file(s) as well. Each line of runtest file contains one test. The first item is the test name. @@ -270,9 +270,9 @@ All other items, separated by space will be executed as a command. Blank lines and lines starting with a ``#`` (comments) are ignored. -Syscalls tests, placed under ``testcases/kernel/syscalls/``, use -``runtest/syscalls`` file. For kernel related tests for memory management we -have ``runtest/mm``, etc. +Syscalls tests, placed under :master:`testcases/kernel/syscalls/`, use +:master:`runtest/syscalls` file. For kernel related tests for memory management we +have :master:`runtest/mm`, etc. .. note:: @@ -286,7 +286,7 @@ Datafiles If your test needs data files, these should be put into a subdirectory named ``datafiles`` and installed into the ``testcases/data/$TCID`` directory. This will require to add ``INSTALL_DIR := testcases/data/TCID`` into -``datafiles/Makefile``. +correspondent ``datafiles/Makefile``. You can obtain path to datafiles via ``$TST_DATAROOT`` provided by ``test.sh`` or via C function ``tst_dataroot()`` provided by libltp: @@ -337,7 +337,7 @@ Testing pre-release kernel features ----------------------------------- Tests for features not yet in the mainline kernel release are accepted. However, -they must be added only to the **staging** runtest file. Once a feature is part +they must be added only to :master:`runtest/staging`. Once a feature is part of the stable kernel ABI, the associated test must be moved out of staging. Testing builds with GitHub Actions diff --git a/doc/users/quick_start.rst b/doc/users/quick_start.rst index 69792999b..4a48745be 100644 --- a/doc/users/quick_start.rst +++ b/doc/users/quick_start.rst @@ -123,4 +123,4 @@ Network tests ------------- Network tests usually require a certain setup that is described in -``testcases/network/README.md``. +:master:`testcases/network/README.md`.
Convert all the files/directory names which actually points to real files/directories to the links to GitHub sources. Exception is datafiles/Makefile and some examples. For now we use link to the master, maybe we want to change that if we ever generate stable docs. Signed-off-by: Petr Vorel <pvorel@suse.cz> --- doc/conf.py | 2 +- doc/developers/test_case_tutorial.rst | 18 +++++++++--------- doc/developers/writing_tests.rst | 22 +++++++++++----------- doc/users/quick_start.rst | 2 +- 4 files changed, 22 insertions(+), 22 deletions(-)