From bebe66feaee45e1e280a63e089bd894bc9227ee5 Mon Sep 17 00:00:00 2001 From: Quentin Schulz Date: Wed, 18 Jun 2025 17:13:35 +0200 Subject: [PATCH] tree-wide: make the :doc: directive use absolute paths This makes all :doc: directives use an absolute paths (with the root directory being documentation/ in the repo). This is then consistent across the whole source and is easier to review and move files around, you just need to know where a file is located relative to documentation/ directory and use that. This gets rid of paths looking in parent directory with '..' as well as expecting a file to be in the same directory as the other file it points to via the :doc: directive. (From yocto-docs rev: b9457f2005b0bea49c54e9727eb30e9458084886) Signed-off-by: Quentin Schulz Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.rst | 4 ++-- documentation/contributor-guide/submit-changes.rst | 4 ++-- documentation/dev-manual/building.rst | 4 ++-- documentation/dev-manual/debugging.rst | 4 ++-- documentation/dev-manual/new-recipe.rst | 2 +- documentation/dev-manual/start.rst | 2 +- documentation/dev-manual/vulnerabilities.rst | 2 +- documentation/migration-guides/release-notes-4.3.rst | 4 ++-- documentation/overview-manual/development-environment.rst | 6 +++--- documentation/ref-manual/resources.rst | 4 ++-- documentation/ref-manual/system-requirements.rst | 2 +- documentation/ref-manual/variables.rst | 2 +- documentation/transitioning-to-a-custom-environment.rst | 4 ++-- documentation/what-i-wish-id-known.rst | 4 ++-- 14 files changed, 24 insertions(+), 24 deletions(-) diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst index 4a24fc3ffc..9fe4ac7722 100644 --- a/documentation/bsp-guide/bsp.rst +++ b/documentation/bsp-guide/bsp.rst @@ -881,7 +881,7 @@ The requirements for a released BSP that conform to the Yocto Project are: ``recipes-*`` subdirectories specific to the recipe's function, or within a subdirectory containing a set of closely-related recipes. The recipes themselves should follow the general guidelines for - recipes found in the ":doc:`../contributor-guide/recipe-style-guide`" + recipes found in the ":doc:`/contributor-guide/recipe-style-guide`" in the Yocto Project and OpenEmbedded Contributor Guide. - *License File:* You must include a license file in the @@ -915,7 +915,7 @@ The requirements for a released BSP that conform to the Yocto Project are: - The name and contact information for the BSP layer maintainer. This is the person to whom patches and questions should be sent. For information on how to find the right person, see the - :doc:`../contributor-guide/submit-changes` section in the Yocto Project and + :doc:`/contributor-guide/submit-changes` section in the Yocto Project and OpenEmbedded Contributor Guide. - Instructions on how to build the BSP using the BSP layer. diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst index 6d5d69d7cf..adb78fa08d 100644 --- a/documentation/contributor-guide/submit-changes.rst +++ b/documentation/contributor-guide/submit-changes.rst @@ -76,7 +76,7 @@ Clone the Git repository for the component to modify ---------------------------------------------------- After identifying the component to modify as described in the -":doc:`../contributor-guide/identify-component`" section, clone the +":doc:`/contributor-guide/identify-component`" section, clone the corresponding Git repository. Here is an example for OpenEmbedded-Core:: git clone https://git.openembedded.org/openembedded-core @@ -872,7 +872,7 @@ in regards to the use of generative AI tools. See: https://www.linuxfoundation.org/legal/generative-ai. All of the existing guidelines in this document are expected to be followed, -including in the :doc:`recipe-style-guide`, and contributing the changes with +including in the :doc:`/contributor-guide/recipe-style-guide`, and contributing the changes with additional requirements to the items in section :ref:`contributor-guide/submit-changes:Implement and commit changes`. diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index 807c665f68..865d2e1b67 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst @@ -48,7 +48,7 @@ The following figure and list overviews the build process: :width: 100% #. *Set up Your Host Development System to Support Development Using the - Yocto Project*: See the ":doc:`start`" section for options on how to get a + Yocto Project*: See the ":doc:`/dev-manual/start`" section for options on how to get a build host ready to use the Yocto Project. #. *Initialize the Build Environment:* Initialize the build environment @@ -113,7 +113,7 @@ The following figure and list overviews the build process: Building Images for Multiple Targets Using Multiple Configurations ================================================================== -See the :doc:`multiconfig` section of the Yocto Project Development Tasks +See the :doc:`/dev-manual/multiconfig` section of the Yocto Project Development Tasks Manual. Building an Initial RAM Filesystem (Initramfs) Image diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 8552b26aea..6c45ccf652 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -890,7 +890,7 @@ The build should work without issue. As with all solved problems, if they originated upstream, you need to submit the fix for the recipe in OE-Core and upstream so that the problem is taken care of at its source. See the -":doc:`../contributor-guide/submit-changes`" section for more information. +":doc:`/contributor-guide/submit-changes`" section for more information. Debugging With the GNU Project Debugger (GDB) Remotely ====================================================== @@ -1261,7 +1261,7 @@ Here are some other tips that you might find useful: :yocto_bugs:`Bugzilla <>`. For information on how to submit a bug against the Yocto Project, see the Yocto Project Bugzilla :yocto_wiki:`wiki page ` - and the ":doc:`../contributor-guide/report-defect`" section. + and the ":doc:`/contributor-guide/report-defect`" section. .. note:: diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst index 9792bd4c1f..c49881efe6 100644 --- a/documentation/dev-manual/new-recipe.rst +++ b/documentation/dev-manual/new-recipe.rst @@ -1401,7 +1401,7 @@ Following Recipe Style Guidelines ================================= When writing recipes, it is good to conform to existing style guidelines. -See the ":doc:`../contributor-guide/recipe-style-guide`" in the Yocto Project +See the ":doc:`/contributor-guide/recipe-style-guide`" in the Yocto Project and OpenEmbedded Contributor Guide for reference. It is common for existing recipes to deviate a bit from this style. diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst index 73548132a3..d77da04276 100644 --- a/documentation/dev-manual/start.rst +++ b/documentation/dev-manual/start.rst @@ -234,7 +234,7 @@ particular working environment and set of practices. - The Yocto Project community encourages you to send patches to the project to fix bugs or add features. If you do submit patches, follow the project commit guidelines for writing good commit - messages. See the ":doc:`../contributor-guide/submit-changes`" + messages. See the ":doc:`/contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. - Send changes to the core sooner than later as others are likely diff --git a/documentation/dev-manual/vulnerabilities.rst b/documentation/dev-manual/vulnerabilities.rst index d901ff975b..5331a63991 100644 --- a/documentation/dev-manual/vulnerabilities.rst +++ b/documentation/dev-manual/vulnerabilities.rst @@ -22,7 +22,7 @@ issues may be impacting Poky and OE-Core. It is up to the maintainers, users, contributors and anyone interested in the issues to investigate and possibly fix them by updating software components to newer versions or by applying patches to address them. It is recommended to work with Poky and OE-Core upstream maintainers and submit -patches to fix them, see ":doc:`../contributor-guide/submit-changes`" for details. +patches to fix them, see ":doc:`/contributor-guide/submit-changes`" for details. Vulnerability check at build time ================================= diff --git a/documentation/migration-guides/release-notes-4.3.rst b/documentation/migration-guides/release-notes-4.3.rst index 0103ac985e..aa3f31a2ce 100644 --- a/documentation/migration-guides/release-notes-4.3.rst +++ b/documentation/migration-guides/release-notes-4.3.rst @@ -272,9 +272,9 @@ New Features / Enhancements in 4.3 - Prominent documentation updates: - - New :doc:`../contributor-guide/index` document. + - New :doc:`/contributor-guide/index` document. - - New :doc:`../dev-manual/security-subjects` chapter in the Development + - New :doc:`/dev-manual/security-subjects` chapter in the Development Tasks Manual. - Long overdue documentation for the :ref:`ref-classes-devicetree` class. diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst index d79173ff55..066d784314 100644 --- a/documentation/overview-manual/development-environment.rst +++ b/documentation/overview-manual/development-environment.rst @@ -240,7 +240,7 @@ and so forth. For information on finding out who is responsible for (maintains) a particular area of code in the Yocto Project, see the - ":doc:`../contributor-guide/identify-component`" + ":doc:`/contributor-guide/identify-component`" section of the Yocto Project and OpenEmbedded Contributor Guide. The Yocto Project ``poky`` Git repository also has an upstream @@ -272,7 +272,7 @@ push them into the "contrib" area and subsequently request that the maintainer include them into an upstream branch. This process is called "submitting a patch" or "submitting a change." For information on submitting patches and changes, see the -":doc:`../contributor-guide/submit-changes`" section in the Yocto Project +":doc:`/contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. In summary, there is a single point of entry for changes into the @@ -347,7 +347,7 @@ Book `__. this type of change, you format the patch and then send the email using the Git commands ``git format-patch`` and ``git send-email``. For information on how to use these scripts, see the - ":doc:`../contributor-guide/submit-changes`" section in the Yocto Project + ":doc:`/contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. Git diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst index 4eaaca942e..bcbc7ebaca 100644 --- a/documentation/ref-manual/resources.rst +++ b/documentation/ref-manual/resources.rst @@ -23,7 +23,7 @@ The Yocto Project gladly accepts contributions. You can submit changes to the project either by creating and sending pull requests, or by submitting patches through email. For information on how to do both as well as information on how to identify the maintainer for each area of -code, see the :doc:`../contributor-guide/index`. +code, see the :doc:`/contributor-guide/index`. .. _resources-bugtracker: @@ -45,7 +45,7 @@ your expectations). For a general procedure and guidelines on how to use Bugzilla to submit a bug against the Yocto Project, see the following: -- The ":doc:`../contributor-guide/report-defect`" +- The ":doc:`/contributor-guide/report-defect`" section in the Yocto Project and OpenEmbedded Contributor Guide. - The Yocto Project :yocto_wiki:`Bugzilla wiki page ` diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst index b64a13320a..14b635013b 100644 --- a/documentation/ref-manual/system-requirements.rst +++ b/documentation/ref-manual/system-requirements.rst @@ -145,7 +145,7 @@ tested on former revisions of "&DISTRO_NAME;", but no longer are: interested in hearing about your experience. For information on how to submit a bug, see the Yocto Project :yocto_wiki:`Bugzilla wiki page ` - and the ":doc:`../contributor-guide/report-defect`" + and the ":doc:`/contributor-guide/report-defect`" section in the Yocto Project and OpenEmbedded Contributor Guide. Required Packages for the Build Host diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index fd14274a13..65c54f3861 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -2576,7 +2576,7 @@ system and gives an overview of their function and contents. You can safely share this directory between multiple builds on the same development machine. For additional information on how the build process gets source files when working behind a firewall or proxy - server, see this specific question in the ":doc:`faq`" + server, see this specific question in the ":doc:`/ref-manual/faq`" chapter. You can also refer to the ":yocto_wiki:`Working Behind a Network Proxy `" Wiki page. diff --git a/documentation/transitioning-to-a-custom-environment.rst b/documentation/transitioning-to-a-custom-environment.rst index 6ff55e5619..a5f55c567a 100644 --- a/documentation/transitioning-to-a-custom-environment.rst +++ b/documentation/transitioning-to-a-custom-environment.rst @@ -8,8 +8,8 @@ Transitioning to a custom environment for systems development .. note:: - So you've finished the :doc:`brief-yoctoprojectqs/index` and - glanced over the document :doc:`what-i-wish-id-known`, the latter contains + So you've finished the :doc:`/brief-yoctoprojectqs/index` and + glanced over the document :doc:`/what-i-wish-id-known`, the latter contains important information learned from other users. You're well prepared. But now, as you are starting your own project, it isn't exactly straightforward what to do. And, the documentation is daunting. We've put together a few hints to diff --git a/documentation/what-i-wish-id-known.rst b/documentation/what-i-wish-id-known.rst index 836097910d..ddee6ad749 100644 --- a/documentation/what-i-wish-id-known.rst +++ b/documentation/what-i-wish-id-known.rst @@ -49,7 +49,7 @@ contact us with other suggestions. their silicon. These layers have names such as "meta-intel" or "meta-ti". Try not to build layers from scratch. If you do have custom silicon, use one of these layers as a guide or template and familiarize yourself with the - :doc:`bsp-guide/index`. + :doc:`/bsp-guide/index`. #. **Do not put everything into one layer:** Use different layers to logically separate information in your build. As an @@ -127,7 +127,7 @@ contact us with other suggestions. You can build and run a specific task for a specific package (including devshell) or even a single recipe. When developers first start using the Yocto Project, the instructions found in the - :doc:`brief-yoctoprojectqs/index` show how to create an image + :doc:`/brief-yoctoprojectqs/index` show how to create an image and then run or flash that image. However, you can actually build just a single recipe. Thus, if some dependency or recipe isn't working, you can just say "bitbake foo" where "foo" is the name for a specific recipe. As you