From patchwork Thu Oct 27 11:39:39 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 14464 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3B5FBFA3742 for ; Thu, 27 Oct 2022 11:39:59 +0000 (UTC) Received: from relay6-d.mail.gandi.net (relay6-d.mail.gandi.net [217.70.183.198]) by mx.groups.io with SMTP id smtpd.web08.5347.1666870788646797863 for ; Thu, 27 Oct 2022 04:39:49 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=ju/NUCVd; spf=pass (domain: bootlin.com, ip: 217.70.183.198, mailfrom: michael.opdenacker@bootlin.com) Received: (Authenticated sender: michael.opdenacker@bootlin.com) by mail.gandi.net (Postfix) with ESMTPSA id 5D29DC0002; Thu, 27 Oct 2022 11:39:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1666870786; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=mTBseegrJLgMbzJNKCkYNg0DYn7WGKypXybVOI1VMTs=; b=ju/NUCVdtJ1wX7BqJU/J/nqtMbns2irZm/nVutS96FsL8a52dQn8IXVBdVWTIjr+OH0ojM 16ZTaCiFNxWSFGVTSDkRecGyxRquDjqkwA5FSZX2Z6qtEqnQk56xBrSNmu7zcZi24vmMqj aBE+vF8lCOb6Hu7Adc8KrpDn3YqjOJv/HKZVBv5Yw7XPdcGJQeo9GnM5DiomUs/BBvloVD 42/nu2+2EylPwK7X4prPqwjsEV2sA2SLNFDwLLyKdzM/Ba0DvU2l01MXF3a1iay+PjKd3n 1e3/CPME+qWLvK95MO9j5DH3IpdCZAl18XmDS2ZXxWD2wKHD5uyYvgRROItzHQ== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 1/3] Documentation/README: formalize guidelines for external link syntax Date: Thu, 27 Oct 2022 13:39:39 +0200 Message-Id: <20221027113941.34972-1-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 27 Oct 2022 11:39:59 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/3425 From: Michael Opdenacker Signed-off-by: Michael Opdenacker --- 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 `__ + +instead of: +`link text `_ + +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. From patchwork Thu Oct 27 11:39:40 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 14466 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3C4FEFA3745 for ; Thu, 27 Oct 2022 11:39:59 +0000 (UTC) Received: from relay9-d.mail.gandi.net (relay9-d.mail.gandi.net [217.70.183.199]) by mx.groups.io with SMTP id smtpd.web10.5366.1666870790628025125 for ; Thu, 27 Oct 2022 04:39:51 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=jOgqQRYh; spf=pass (domain: bootlin.com, ip: 217.70.183.199, mailfrom: michael.opdenacker@bootlin.com) Received: (Authenticated sender: michael.opdenacker@bootlin.com) by mail.gandi.net (Postfix) with ESMTPSA id 3B52FFF805; Thu, 27 Oct 2022 11:39:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1666870788; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=dv60TlF5fNp0Kvt4A9qh/LGOCXNVmzPR2/YxBH3U/4Q=; b=jOgqQRYhxCKktbdZtzMB1+fEDupL5VmFIELLciPb/8Iq8+SC7FjncMxe1RSovRbItwi0Lm rnbGOSRRUDPWJ6WA3kK2HRgnwtO0ht6oPN4CjGO9JflgYcZVU2kyA3tnzzFZENOGqQOeEw 1f66AI5cZZ3/Nwzsnz11kzfeZDe/J7a4tvYsk3rpdB83qywD4XN+Mb/IN/gTyJ1p6pspfP giX1d29etOfNv7G1e7M4rwJEYfnhrMukBhnM9Y/vGtwuz9AmflI56+FF5B+ZaQeOIdWzji Aw8kRoanGiQ2N9ZrOktXJ53EZKvszyWoHtAjxyANsgZPD/pNI/5uA7r33upFrA== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 2/3] manuals: replace "_" by "__" in external links Date: Thu, 27 Oct 2022 13:39:40 +0200 Message-Id: <20221027113941.34972-2-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221027113941.34972-1-michael.opdenacker@bootlin.com> References: <20221027113941.34972-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 27 Oct 2022 11:39:59 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/3426 From: Michael Opdenacker Signed-off-by: Michael Opdenacker --- 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 -`_ as published by Creative +`__ 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 `_), which - is NPM's public registry. + publish your module in the `NPM registry `__, + which is NPM's public registry. - Be familiar with :doc:`devtool `. 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 `_. + to the official documentation of the `Linux kernel `__. 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 `_ +`deprecated `__ 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 `_ + `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 `_, - `meta-openembedded/meta-python `_ + `meta-openembedded/meta-oe `__, + `meta-openembedded/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 `_ syntax. + `glob `__ 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 `_ + `glob `__ 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 `_ + Specifies `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 -`_, which shares information about why +`__, 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 From patchwork Thu Oct 27 11:39:41 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 14465 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3AA98FA3743 for ; Thu, 27 Oct 2022 11:39:59 +0000 (UTC) Received: from relay11.mail.gandi.net (relay11.mail.gandi.net [217.70.178.231]) by mx.groups.io with SMTP id smtpd.web10.5367.1666870797441879707 for ; Thu, 27 Oct 2022 04:39:57 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=UCN7Gjul; spf=pass (domain: bootlin.com, ip: 217.70.178.231, mailfrom: michael.opdenacker@bootlin.com) Received: (Authenticated sender: michael.opdenacker@bootlin.com) by mail.gandi.net (Postfix) with ESMTPSA id AE066100003; Thu, 27 Oct 2022 11:39:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1666870794; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8lqEcnog5t+MgC4DFyTyaX+s33A+Qes/KFs8eVtNg18=; b=UCN7Gjulf1KnAdzmbyPyXREsq3ZzvDdCAlCVnQ/eWjDhgpGmItgwEgXBCvSrzmiO8nMjgF ldyTL07aXFucpJynYbSXOvMA5Gvm0cfpd865G/UCEaoxUC9Zl2ukqP9wLBWrXGHbIVrpgs Tc9T5j/kmfOIXRhGhfEiJsQLubi+tYuYzq09RhF03AcflGeK1zr0rO9ZR7MKHQbHh2crcn gVxWRlFr7uVRLL9RYhJO8aPvCe22HbEVuFql5ZiTCGeF6YHRRoyk2egJ5oWMLU0CGJoB4U 2a/qySPMcelTlwR8MkM/Fb+amOydshW2Kust/J8ivy5uoxVNQ3uXqu17Ay3jzg== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 3/3] manuals: stop referring to the meta-openembedded repo from GitHub Date: Thu, 27 Oct 2022 13:39:41 +0200 Message-Id: <20221027113941.34972-3-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221027113941.34972-1-michael.opdenacker@bootlin.com> References: <20221027113941.34972-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 27 Oct 2022 11:39:59 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/3427 From: Michael Opdenacker Signed-off-by: Michael Opdenacker --- 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 `". An example of -this type of layer is OpenEmbedded's -`meta-openembedded `__ +this type of layer is OpenEmbedded's :oe_git:`meta-openbedded ` 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 ` + 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 `__ + In some cases, such as with OpenEmbedded's :oe_git:`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 `__, - `meta-openembedded/meta-python `__ - and so on. + :oe_git:`meta-oe `, :oe_git:`meta-python + ` and so on. On the other hand, some container layers (such as :yocto_git:`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. `__ for details. - For example, this variable is used in the - `core-image-minimal-xfce.bb - `__ + For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb + ` recipe:: SYSTEMD_DEFAULT_TARGET = "graphical.target"