Documentation/README: formalize guidelines for external link syntax
PATCH 1/3 Documentation/README: formalize guidelines for external link syntax
From: Michael Opdenacker <[email protected]>
Signed-off-by Michael Opdenacker <[email protected]>
--- documentation/README | 13 +++++++++++++ 1 file changed, 13 insertions(+)
documentation/README +13 -0
@@ -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.
Signature · 1 line
2.34.1
PATCH 2/3 manuals: replace "_" by "__" in external links
From: Michael Opdenacker <[email protected]>
Signed-off-by Michael Opdenacker <[email protected]>
--- 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(-)
documentation/boilerplate.rst +1 -1
@@ -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)
documentation/dev-manual/common-tasks.rst +2 -3
@@ -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>`.
documentation/ref-manual/classes.rst +2 -2
@@ -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:
documentation/ref-manual/terms.rst +3 -3
@@ -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
documentation/ref-manual/variables.rst +3 -3
@@ -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.
documentation/test-manual/reproducible-builds.rst +1 -1
@@ -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
Signature · 1 line
2.34.1
PATCH 3/3 manuals: stop referring to the meta-openembedded repo from GitHub
In reply to [email protected]From: Michael Opdenacker <[email protected]>
Signed-off-by Michael Opdenacker <[email protected]>
--- 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(-)
documentation/bsp-guide/bsp.rst +1 -2
@@ -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::
documentation/dev-manual/common-tasks.rst +2 -2
@@ -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.
documentation/ref-manual/terms.rst +3 -5
@@ -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>`)
documentation/ref-manual/variables.rst +2 -3
@@ -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"
Signature · 1 line
2.34.1