[LTP] [PATCH v1] doc: introduce sphinx extlinks
Andrea Cervesato
andrea.cervesato@suse.de
Fri Apr 19 16:07:52 CEST 2024
From: Andrea Cervesato <andrea.cervesato@suse.com>
With sphinx extlinks we are now able to avoid duplication of the
github repo link inside documentation. The patch introduces two new
directives which can be used: :repo: and :master:, which are used to
replace repo static link and repo master static link respectively.
Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
doc/conf.py | 7 ++++++-
doc/developers/test_case_tutorial.rst | 5 ++---
doc/developers/writing_tests.rst | 4 ++--
doc/maintainers/ltp_release_procedure.rst | 18 ++++++++----------
doc/users/quick_start.rst | 2 +-
doc/users/supported_systems.rst | 4 +++-
6 files changed, 22 insertions(+), 18 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index fb3e83cf2..9408ee46e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -22,10 +22,15 @@ release = '1.0'
extensions = [
'linuxdoc.rstKernelDoc',
- 'sphinxcontrib.spelling'
+ 'sphinxcontrib.spelling',
+ 'sphinx.ext.extlinks'
]
exclude_patterns = ["html*", '_static*']
+extlinks = {
+ 'repo': ('https://github.com/linux-test-project/ltp/%s', '%s'),
+ 'master': ('https://github.com/linux-test-project/ltp/blob/master/%s', '%s')
+}
spelling_lang = "en_US"
spelling_warning = True
diff --git a/doc/developers/test_case_tutorial.rst b/doc/developers/test_case_tutorial.rst
index fc56ae58c..71777cffc 100644
--- a/doc/developers/test_case_tutorial.rst
+++ b/doc/developers/test_case_tutorial.rst
@@ -627,9 +627,8 @@ again on the hard-link, then ``stat`` the file".
Because we are now opening a file, we need a ``cleanup`` function to close the
file descriptors. We have to manually close the files to ensure the temporary
-directory is deleted by the test harness (see the
-https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[test
-writing guidelines] for details).
+directory is deleted by the test harness (see the test writing guidelines for
+details).
As a matter of good practice, the file descriptors are closed in reverse
order. In some circumstances the order which ``cleanup`` is performed is
diff --git a/doc/developers/writing_tests.rst b/doc/developers/writing_tests.rst
index 032fbcbd5..2eaf5f9e5 100644
--- a/doc/developers/writing_tests.rst
+++ b/doc/developers/writing_tests.rst
@@ -343,11 +343,11 @@ of the stable kernel ABI, the associated test must be moved out of staging.
Testing builds with GitHub Actions
----------------------------------
-Master branch is tested in `GitHub Actions <https://github.com/linux-test-project/ltp/actions>`_
+Master branch is tested in GitHub :repo:`actions`
to ensure LTP builds in various distributions, including old, current and
bleeding edge. ``gcc`` and ``clang`` toolchains are also tested for various
architectures using cross-compilation. For a full list of tested distros, please
-check ``.github/workflows/ci.yml``.
+check :repo:`.github/workflows/ci.yml`.
.. note::
diff --git a/doc/maintainers/ltp_release_procedure.rst b/doc/maintainers/ltp_release_procedure.rst
index f0bc01cee..53eb02855 100644
--- a/doc/maintainers/ltp_release_procedure.rst
+++ b/doc/maintainers/ltp_release_procedure.rst
@@ -44,9 +44,9 @@ Tag the git and push changes to github
The string ``YYYYMMDD`` should be substituted to the current date.
-You can use `tools/tag-release.sh <https://github.com/linux-test-project/ltp/blob/master/tools/tag-release.sh>`_
-script to have the above automated process.
-It allows you to verify the tag before pushing it and does other checks.
+You can use :master:`tools/tag-release.sh` script to have the above automated
+process. It allows you to verify the tag before pushing it and does other
+checks.
.. code-block:: bash
@@ -121,9 +121,9 @@ metadata documentation:
make -C metadata
cp -v docparse/metadata.html ../metadata.YYYYMMDD.html
-You can use `tools/create-tarballs-metadata.sh <https://github.com/linux-test-project/ltp/blob/master/tools/create-tarballs-metadata.sh>`_
-script to have the above procedure automated. All generated files are placed
-in the ``ltp-release-YYYYMMDD`` directory.
+You can use :master:`tools/create-tarballs-metadata.sh` script to have the above
+procedure automated. All generated files are placed in the
+``ltp-release-YYYYMMDD`` directory.
.. code-block:: bash
@@ -149,10 +149,8 @@ in the ``ltp-release-YYYYMMDD`` directory.
Upload the generated files to GitHub
------------------------------------
-Click on `Releases <https://github.com/linux-test-project/ltp/releases>`_, then
-switch to `Tags <https://github.com/linux-test-project/ltp/tags>`_. Click on
-'Add release notes'. There should be 'Attach binaries ...' link at the
-bottom of the page.
+Go to :repo:`tags`. Click on ``Add release notes``.
+There should be ``Attach binaries ...`` link at the bottom of the page.
Don't forget to upload checksums for the tarballs and metadata documentation
as well.
diff --git a/doc/users/quick_start.rst b/doc/users/quick_start.rst
index 40d8dd9c6..69792999b 100644
--- a/doc/users/quick_start.rst
+++ b/doc/users/quick_start.rst
@@ -24,7 +24,7 @@ Basics requirements to build LTP are the following:
.. note::
- For optional library dependencies, take a look at the scripts inside ``ci/``
+ For optional library dependencies, take a look at the scripts inside :master:`ci/`
directory.
Running single tests
diff --git a/doc/users/supported_systems.rst b/doc/users/supported_systems.rst
index 6220a96e0..4ac2bb08c 100644
--- a/doc/users/supported_systems.rst
+++ b/doc/users/supported_systems.rst
@@ -44,6 +44,8 @@ Oldest tested distributions
- 2.17
- \-
+For a full list of tested distros, please check :master:`.github/workflows/ci.yml`.
+
Older distributions are not officially supported, which means that it
may or may not work. It all depends on your luck. It should be possible
to compile latest LTP even on slightly older distributions than we
@@ -99,7 +101,7 @@ Supported C libraries
- Older uClibc might have problems.
* - `musl <https://musl.libc.org/>`_
- - Not yet fully supported. Check ``ci/alpine.sh`` script.
+ - Not yet fully supported. Check :master:`ci/alpine.sh` script.
* - Android
- Please use `AOSP fork <https://android.googlesource.com/platform/external/ltp>`_
--
2.35.3
More information about the ltp
mailing list