diff mbox series

[v1] doc: introduce sphinx extlinks

Message ID 20240419140752.18003-1-andrea.cervesato@suse.de
State Accepted
Headers show
Series [v1] doc: introduce sphinx extlinks | expand

Commit Message

Andrea Cervesato April 19, 2024, 2:07 p.m. UTC 
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(-)

Comments

Petr Vorel April 19, 2024, 6:47 p.m. UTC | #1 
Hi Andrea,

Thanks a lot, merged!

I'm a bit disappointed that such simple thing as code formatting part of the
link (or whole link) is not possible, but it's a detail. Having links on single
place is an improvement.

NOTE: I still need to trigger doc build manually.

...
> +++ 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).

I dared to fix this as a link (in a separate commit):

directory is deleted by the test harness (see :doc:`writing_tests` for details).

Kind regards,
Petr
Petr Vorel April 19, 2024, 6:52 p.m. UTC | #2 
Hi Andrea,

> Hi Andrea,

> NOTE: I still need to trigger doc build manually.

I'm sorry, this time it worked out of the box, great :).
I see green "passing" in the dashboard [1].

Although I still see "Could not add webhook for "linux-test-project". Please
connect your GitHub account." in project account [2].

Kind regards,
Petr

[1] https://readthedocs.org/dashboard/
[2] https://readthedocs.org/projects/linux-test-project/
diff mbox series

Patch

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