[PATCH 1/3] Documentation/README: formalize guidelines for external link syntax

[PATCH 1/3] Documentation/README: formalize guidelines for external link syntax

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/README | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/documentation/README b/documentation/README
index 6333f0496a..c27ed86a33 100644
--- a/documentation/README
+++ b/documentation/README
@@ -275,6 +275,19 @@ websites.
 More information can be found here:
 https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html.
 
+For external links, we use this syntax:
+`link text <link URL>`__
+
+instead of:
+`link text <link URL>`_
+
+Both syntaxes work, but the latter also creates a "link text" reference
+target which could conflict with other references with the same name.
+So, only use this variant when you wish to make multiple references
+to this link, reusing only the target name.
+
+See https://stackoverflow.com/questions/27420317/restructured-text-rst-http-links-underscore-vs-use
+
 Anchor (<#link>) links are forbidden as they are not checked by Sphinx during
 the build and may be broken without knowing about it.
 
-- 
2.34.1

[PATCH 2/3] manuals: replace "_" by "__" in external links

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/boilerplate.rst                     | 2 +-
 documentation/dev-manual/common-tasks.rst         | 5 ++---
 documentation/ref-manual/classes.rst              | 4 ++--
 documentation/ref-manual/terms.rst                | 6 +++---
 documentation/ref-manual/variables.rst            | 6 +++---
 documentation/test-manual/reproducible-builds.rst | 2 +-
 6 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/documentation/boilerplate.rst b/documentation/boilerplate.rst
index 9b64d91efd..ad7bb64956 100644
--- a/documentation/boilerplate.rst
+++ b/documentation/boilerplate.rst
@@ -8,7 +8,7 @@
 
 Permission is granted to copy, distribute and/or modify this document under the
 terms of the `Creative Commons Attribution-Share Alike 2.0 UK: England & Wales
-<https://creativecommons.org/licenses/by-sa/2.0/uk/>`_ as published by Creative
+<https://creativecommons.org/licenses/by-sa/2.0/uk/>`__ as published by Creative
 Commons.
 
 To report any inaccuracies or problems with this (or any other Yocto Project)
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 53e7686633..c3defa0766 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -7547,9 +7547,8 @@ NPM packages:
 -  Of the two methods that you can use ``devtool`` to create NPM
    packages, the registry approach is slightly simpler. However, you
    might consider the project approach because you do not have to
-   publish your module in the NPM registry
-   (`npm-registry <https://docs.npmjs.com/misc/registry>`_), which
-   is NPM's public registry.
+   publish your module in the `NPM registry <https://docs.npmjs.com/misc/registry>`__,
+   which is NPM's public registry.
 
 -  Be familiar with
    :doc:`devtool </ref-manual/devtool-reference>`.
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 1880e44486..a1c563f308 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1738,7 +1738,7 @@ is supported by ``overlayfs``. This has to be done in your machine configuration
   * QA checks fail to catch file existence if you redefine this variable in your recipe!
   * Only the existence of the systemd mount unit file is checked, not its contents.
   * To get more details on ``overlayfs``, its internals and supported operations, please refer
-    to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_.
+    to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`__.
 
 The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
 (e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
@@ -2485,7 +2485,7 @@ build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and have
 not migrated to the official ``pyproject.toml`` format). Unlike
 ``setuptools3.bbclass``, this uses the traditional ``setup.py`` ``build`` and
 ``install`` commands and not wheels. This use of ``setuptools`` like this is
-`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`_
+`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`__
 but still relatively common.
 
 .. _ref-classes-setuptools3-base:
diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
index 1e3f718a8f..1a2c055591 100644
--- a/documentation/ref-manual/terms.rst
+++ b/documentation/ref-manual/terms.rst
@@ -139,12 +139,12 @@ universal, the list includes them just in case:
       be included independently in your project's ``bblayers.conf`` file.
 
       In some cases, such as with OpenEmbedded's
-      `meta-openembedded <https://github.com/openembedded/meta-openembedded>`_
+      `meta-openembedded <https://github.com/openembedded/meta-openembedded>`__
       layer, the top level ``meta-openembedded/`` directory is not itself an actual layer,
       so you would never explicitly include it in a ``bblayers.conf`` file;
       rather, you would include any number of its layer subdirectories, such as
-      `meta-openembedded/meta-oe <https://github.com/openembedded/meta-openembedded/tree/master/meta-oe>`_,
-      `meta-openembedded/meta-python <https://github.com/openembedded/meta-openembedded/tree/master/meta-python>`_
+      `meta-openembedded/meta-oe <https://github.com/openembedded/meta-openembedded/tree/master/meta-oe>`__,
+      `meta-openembedded/meta-python <https://github.com/openembedded/meta-openembedded/tree/master/meta-python>`__
       and so on.
 
       On the other hand, some container layers (such as
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 71e8c272a7..59882fb158 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -615,7 +615,7 @@ system and gives an overview of their function and contents.
       software.
 
       When specifying recipe files, you can pattern match using Python's
-      `glob <https://docs.python.org/3/library/glob.html>`_ syntax.
+      `glob <https://docs.python.org/3/library/glob.html>`__ syntax.
       For details on the syntax, see the documentation by following the
       previous link.
 
@@ -2481,7 +2481,7 @@ system and gives an overview of their function and contents.
 
          -  When specifying files or paths, you can pattern match using
             Python's
-            `glob <https://docs.python.org/3/library/glob.html>`_
+            `glob <https://docs.python.org/3/library/glob.html>`__
             syntax. For details on the syntax, see the documentation by
             following the previous link.
 
@@ -4943,7 +4943,7 @@ system and gives an overview of their function and contents.
       See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
 
    :term:`module_conf`
-      Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`_
+      Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__
       syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
       file.
 
diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst
index 5977366c9e..61127de23c 100644
--- a/documentation/test-manual/reproducible-builds.rst
+++ b/documentation/test-manual/reproducible-builds.rst
@@ -19,7 +19,7 @@ Why it matters
 ==============
 
 The project aligns with the `Reproducible Builds project
-<https://reproducible-builds.org/>`_, which shares information about why
+<https://reproducible-builds.org/>`__, which shares information about why
 reproducibility matters. The primary focus of the project is the ability to
 detect security issues being introduced. However, from a Yocto Project
 perspective, it is also hugely important that our builds are deterministic. When
-- 
2.34.1

[PATCH 3/3] manuals: stop referring to the meta-openembedded repo from GitHub

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/bsp-guide/bsp.rst           | 3 +--
 documentation/dev-manual/common-tasks.rst | 4 ++--
 documentation/ref-manual/terms.rst        | 8 +++-----
 documentation/ref-manual/variables.rst    | 5 ++---
 4 files changed, 8 insertions(+), 12 deletions(-)

diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index 7e17b42886..efdaf80f63 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -109,8 +109,7 @@ them to the "Dependencies" section.
 
 Some layers function as a layer to hold other BSP layers. These layers
 are known as ":term:`container layers <Container Layer>`". An example of
-this type of layer is OpenEmbedded's
-`meta-openembedded <https://github.com/openembedded/meta-openembedded>`__
+this type of layer is OpenEmbedded's :oe_git:`meta-openbedded </meta-openembedded>`
 layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers.
 In cases like this, you need to include the names of the actual layers
 you want to work with, such as::
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index c3defa0766..f24fa4dbb5 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -7555,8 +7555,8 @@ NPM packages:
 
 -  The NPM host tools need the native ``nodejs-npm`` package, which is
    part of the OpenEmbedded environment. You need to get the package by
-   cloning the https://github.com/openembedded/meta-openembedded
-   repository out of GitHub. Be sure to add the path to your local copy
+   cloning the :oe_git:`meta-openembedded </meta-openembedded>`
+   repository. Be sure to add the path to your local copy
    to your ``bblayers.conf`` file.
 
 -  ``devtool`` cannot detect native libraries in module dependencies.
diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst
index 1a2c055591..ee14df5684 100644
--- a/documentation/ref-manual/terms.rst
+++ b/documentation/ref-manual/terms.rst
@@ -138,14 +138,12 @@ universal, the list includes them just in case:
       which contains multiple (and typically related) sub-layers which can
       be included independently in your project's ``bblayers.conf`` file.
 
-      In some cases, such as with OpenEmbedded's
-      `meta-openembedded <https://github.com/openembedded/meta-openembedded>`__
+      In some cases, such as with OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
       layer, the top level ``meta-openembedded/`` directory is not itself an actual layer,
       so you would never explicitly include it in a ``bblayers.conf`` file;
       rather, you would include any number of its layer subdirectories, such as
-      `meta-openembedded/meta-oe <https://github.com/openembedded/meta-openembedded/tree/master/meta-oe>`__,
-      `meta-openembedded/meta-python <https://github.com/openembedded/meta-openembedded/tree/master/meta-python>`__
-      and so on.
+      :oe_git:`meta-oe </meta-openembedded/tree/meta-oe>`, :oe_git:`meta-python
+      </meta-openembedded/tree/meta-python>` and so on.
 
       On the other hand, some container layers (such as
       :yocto_git:`meta-security </meta-security>`)
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 59882fb158..1721b7fe69 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7896,9 +7896,8 @@ system and gives an overview of their function and contents.
       <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__
       for details.
 
-      For example, this variable is used in the
-      `core-image-minimal-xfce.bb
-      <https://git.openembedded.org/meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>`__
+      For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb
+      </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>`
       recipe::
 
           SYSTEMD_DEFAULT_TARGET = "graphical.target"
-- 
2.34.1