[LTP] [PATCH 1/1] doc: Link file/directory names to GitHub sources

[Andrea Cervesato]

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`.