Improve/simplify references to the BitBake manual
A message that is not in the archive (sent off-list or not yet received): [email protected]
v2 cover Improve/simplify references to the BitBake manual
This new version:
- Updates the guidelines about refering to variable descriptions in the BitBake manual
- Explains the simplifications made to the references to the BitBake manual
- Add a new commit to replace explicit references to term descriptions in the BitBake manual by generic term references. Such descriptions are taken first from the Yocto Project Variable Glossary, or otherwise from the BitBake manual.
*** BLURB HERE ***
Michael Opdenacker (3):
documentation/README: improve BitBake manual referencing guidelines
manuals: simplify references to BitBake manual
manuals: remove explicit BitBake variable references
documentation/README | 15 ++++++++++++--- documentation/brief-yoctoprojectqs/index.rst | 4 ++-- documentation/dev-manual/common-tasks.rst | 8 ++++---- .../migration-guides/migration-2.4.rst | 4 ++-- .../migration-guides/migration-3.0.rst | 2 +- documentation/overview-manual/concepts.rst | 12 +++++------- documentation/ref-manual/tasks.rst | 4 ++-- documentation/ref-manual/variables.rst | 17 ++++++++--------- documentation/sdk-manual/extensible.rst | 2 +- 9 files changed, 37 insertions(+), 31 deletions(-)
Signature · 1 line
2.25.1
PATCH v2 1/3 documentation/README: improve BitBake manual referencing guidelines
Removing the ":ref:`-D <bitbake:..." syntax as it's not necessary Adding more and simpler ways of making references to the BitBake manual.
--- documentation/README | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-)
documentation/README +12 -3
@@ -328,10 +328,19 @@ The sphinx.ext.intersphinx extension is enabled by default so that we can cross reference content from other Sphinx based documentation projects, such as the BitBake manual. -References to the bitbake manual can be done like this: +References to the BitBake manual can be done: + - With a specific description instead of the section name: + :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` + - With the section name: + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option + - Linking to the entire BitBake manual: + :doc:`BitBake User Manual <bitbake:index>` + +Note that a reference to a variable (:term:`VARIABLE`) automatically points to +the BitBake manual if the variable is not described in the Reference Manual's Variable Glossary. +However, if you need to bypass this, you can explicitely refer to a description in the +BitBake manual as follows: - See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option -or :term:`bitbake:BB_NUMBER_PARSE_THREADS` Submitting documentation changes
Signature · 1 line
2.25.1
PATCH v2 2/3 manuals: simplify references to BitBake manual
In reply to Michael OpdenackerReplacing ":ref:section name<bitbake:bitbake-user-manual/bitbake-user-manual-<section>:section name>" by ":ref:bitbake:bitbake-user-manual/bitbake-user-manual-<section>:section name" when the reference description is the same as the section name.
In this case, that's unnecessary to repeat the section name in the description part.
--- documentation/brief-yoctoprojectqs/index.rst | 4 ++-- documentation/dev-manual/common-tasks.rst | 2 +- documentation/migration-guides/migration-2.4.rst | 4 ++-- documentation/overview-manual/concepts.rst | 6 +++--- documentation/ref-manual/tasks.rst | 4 ++-- documentation/ref-manual/variables.rst | 12 ++++++------ documentation/sdk-manual/extensible.rst | 2 +- 7 files changed, 17 insertions(+), 17 deletions(-)
documentation/brief-yoctoprojectqs/index.rst +2 -2
@@ -267,8 +267,8 @@ an entire Linux distribution, including the toolchain, from source. For information on using the ``bitbake`` command, see the :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and - Concepts Manual, or see the ":ref:`BitBake Command - <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. + Concepts Manual, or see the + :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` section in the BitBake User Manual. #. **Simulate Your Image Using QEMU:** Once this particular image is built, you can start QEMU, which is a Quick EMUlator that ships with
documentation/dev-manual/common-tasks.rst +1 -1
@@ -9358,7 +9358,7 @@ log to ``${T}/log.do_``\ `task`, and can also log to standard output - ``bb.debug(level, msg)``: Writes "DEBUG: msg" to the log. Also logs to stdout if the log level is greater than or equal to - level. See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option + level. See the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax`" option in the BitBake User Manual for more information. - ``bb.warn(msg)``: Writes "WARNING: msg" to the log while also
documentation/migration-guides/migration-2.4.rst +2 -2
@@ -286,8 +286,8 @@ The following are additional changes: - BitBake fires multiple "BuildStarted" events when multiconfig is enabled (one per configuration). For more information, see the - ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User - Manual. + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events`" + section in the BitBake User Manual. - By default, the ``security_flags.inc`` file sets a :term:`GCCPIE` variable with an option to enable
documentation/overview-manual/concepts.rst +3 -3
@@ -74,7 +74,7 @@ versions of ``matchbox-desktop`` might exist. BitBake chooses the one selected by the distribution configuration. You can get more details about how BitBake chooses between different target versions and providers in the -":ref:`Preferences <bitbake:bitbake-user-manual/bitbake-user-manual-execution:preferences>`" section +":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:preferences`" section of the BitBake User Manual. BitBake also tries to execute any dependent tasks first. So for example,
@@ -584,7 +584,7 @@ Source Control Managers (Optional) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another place from which the build system can get source files is with -:ref:`fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` employing various Source +:ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers` employing various Source Control Managers (SCMs) such as Git or Subversion. In such cases, a repository is cloned or checked out. The :ref:`ref-tasks-fetch` task inside
@@ -1863,7 +1863,7 @@ The following list explains the previous example: through the shared state cache if possible. If the task was accelerated, ``sstate_setscene()`` returns True. Otherwise, it returns False, and the normal ``do_deploy`` task runs. For more - information, see the ":ref:`setscene <bitbake:bitbake-user-manual/bitbake-user-manual-execution:setscene>`" + information, see the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:setscene`" section in the BitBake User Manual. - The ``do_deploy[dirs] = "${DEPLOYDIR} ${B}"`` line creates
documentation/ref-manual/tasks.rst +2 -2
@@ -14,8 +14,8 @@ Normal Recipe Build Tasks The following sections describe normal tasks associated with building a recipe. For more information on tasks and dependencies, see the -":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and -":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the +":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and +":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the BitBake User Manual. .. _ref-tasks-build:
documentation/ref-manual/variables.rst +6 -6
@@ -256,7 +256,7 @@ system and gives an overview of their function and contents. To add a tune to the list, be sure to append it with spaces using the "+=" BitBake operator. Do not simply replace the list by using the "=" operator. See the - ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake User Manual for more information. :term:`AZ_SAS`
@@ -1638,8 +1638,8 @@ system and gives an overview of their function and contents. For information on runtime dependencies, see the :term:`RDEPENDS` variable. You can also see the - ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and - ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the BitBake User Manual for additional information on tasks and dependencies.
@@ -6105,8 +6105,8 @@ system and gives an overview of their function and contents. For information on build-time dependencies, see the :term:`DEPENDS` variable. You can also see the - ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and - ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the BitBake User Manual for additional information on tasks and dependencies.
@@ -6951,7 +6951,7 @@ system and gives an overview of their function and contents. protocols are highly dependent on particular BitBake Fetcher submodules. Depending on the fetcher BitBake uses, various URL parameters are employed. For specifics on the supported Fetchers, see - the ":ref:`Fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`" section in the + the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual. - ``file://`` - Fetches files, which are usually files shipped
documentation/sdk-manual/extensible.rst +1 -1
@@ -614,7 +614,7 @@ specify source code revision and versioning schemes, extract code into or out of the ``devtool`` :ref:`devtool-the-workspace-layer-structure`, and work with any source file forms that the -:ref:`fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` support. +:ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers` support. The following diagram shows the common development flow used with the ``devtool upgrade`` command:
Signature · 1 line
2.25.1
Re: [docs] [PATCH v2 2/3] manuals: simplify references to BitBake manual
Hi Michael,
Quoted 21 lines · Michael Opdenacker
Replacing ":ref:
section name<bitbake:bitbake-user-manual/bitbake-user-manual-<section>:section name>" by ":ref:bitbake:bitbake-user-manual/bitbake-user-manual-<section>:section name" when the reference description is the same as the section name.
In this case, that's unnecessary to repeat the section name in the description part.Signed-off-by Michael Opdenacker <[email protected]>--- documentation/brief-yoctoprojectqs/index.rst | 4 ++-- documentation/dev-manual/common-tasks.rst | 2 +- documentation/migration-guides/migration-2.4.rst | 4 ++-- documentation/overview-manual/concepts.rst | 6 +++--- documentation/ref-manual/tasks.rst | 4 ++-- documentation/ref-manual/variables.rst | 12 ++++++------ documentation/sdk-manual/extensible.rst | 2 +- 7 files changed, 17 insertions(+), 17 deletions(-)documentation/brief-yoctoprojectqs/index.rst +0
-0
documentation/brief-yoctoprojectqs/index.rst an entire Linux distribution, including the toolchain, from source. · line 270
Quoted 6 lines
documentation/brief-yoctoprojectqs/index.rst +1
-2@@ -267,8 +267,8 @@ an entire Linux distribution, including the toolchain, from source. For information on using the ``bitbake`` command, see the :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and - Concepts Manual, or see the ":ref:`BitBake Command - <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. + Concepts Manual, or see the
Spurious the since I assume it's part of the section title just below.
documentation/brief-yoctoprojectqs/index.rst an entire Linux distribution, including the toolchain, from source. · line 271
Quoted 1 line
documentation/brief-yoctoprojectqs/index.rst +1
-0+ :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command` section in the BitBake User Manual.
Otherwise,
Cheers,
Quentin
Re: [docs] [PATCH v2 2/3] manuals: simplify references to BitBake manual
Hi Quentin,
Thanks for your review!
Quoted 25 lines · Quentin Schulz
Hi Michael,
Quoted 22 lines · Michael Opdenacker
Replacing ":ref:
section name<bitbake:bitbake-user-manual/bitbake-user-manual-<section>:section name>" by ":ref:bitbake:bitbake-user-manual/bitbake-user-manual-<section>:section name" when the reference description is the same as the section name.
In this case, that's unnecessary to repeat the section name in the description part.Signed-off-by Michael Opdenacker <[email protected]>--- documentation/brief-yoctoprojectqs/index.rst | 4 ++-- documentation/dev-manual/common-tasks.rst | 2 +- documentation/migration-guides/migration-2.4.rst | 4 ++-- documentation/overview-manual/concepts.rst | 6 +++--- documentation/ref-manual/tasks.rst | 4 ++-- documentation/ref-manual/variables.rst | 12 ++++++------ documentation/sdk-manual/extensible.rst | 2 +- 7 files changed, 17 insertions(+), 17 deletions(-)documentation/brief-yoctoprojectqs/index.rst +0
-0@@ -267,8 +267,8 @@ an entire Linux distribution, including the toolchain, from source.
Quoted 6 lines
documentation/brief-yoctoprojectqs/index.rst an entire Linux distribution, including the toolchain, from source. · line 270
Quoted 5 lines
documentation/brief-yoctoprojectqs/index.rst +1
-2For information on using the ``bitbake`` command, see the :ref:`overview-manual/concepts:bitbake` section in the Yocto Project Overview and - Concepts Manual, or see the ":ref:`BitBake Command - <bitbake:bitbake-user-manual/bitbake-user-manual-intro:the bitbake command>`" section in the BitBake User Manual. + Concepts Manual, or see theSpurious
thesince I assume it's part of the section title just below.
Actually, this one was intentional, as "The" is part of the section name. The result is:
"see the The BitBake Command
<https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#the-bitbake-command> section
in the BitBake User Manual"
I could put "The BitBake Command" between double quotes, but I agree that this still sounds weird if you read out loud.
I could either revert the change or just drop "the" and "section" and get:
"see The BitBake Command in the BitBake User Manual"
Any preference? The second solution has the simplest source code. Thanks again,
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
A message that is not in the archive (sent off-list or not yet received): [email protected]
Re: [docs] [PATCH v2 2/3] manuals: simplify references to BitBake manual
Hello,
Quoted 6 lines · Michael Opdenacker
Actually, this one was intentional, as "The" is part of the section name. The result is:
"see the The BitBake Command
<https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-intro.html#the-bitbake-command> section
in the BitBake User Manual"
Quoted 7 lines
I could put "The BitBake Command" between double quotes, but I agree that this still sounds weird if you read out loud.
I could either revert the change or just drop "the" and "section" and get:
"see The BitBake Command in the BitBake User Manual"Any preference? The second solution has the simplest source code.
I eventually chose the simplest solution (the second one) and merged my 3 commits into "master-next".
Thanks again for the reviews!
Cheers,
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
PATCH v2 3/3 manuals: remove explicit BitBake variable references
In reply to Michael OpdenackerThe standard :term:VARIABLE will refer to the description of the variable in the YP variable index. If it doesn't exist, it will refer to the description of the variable in the BitBake manual.
--- documentation/dev-manual/common-tasks.rst | 6 +++--- documentation/migration-guides/migration-3.0.rst | 2 +- documentation/overview-manual/concepts.rst | 6 ++---- documentation/ref-manual/variables.rst | 5 ++--- 4 files changed, 8 insertions(+), 11 deletions(-)
documentation/dev-manual/common-tasks.rst +3 -3
@@ -4384,7 +4384,7 @@ directory: variable, inherit the :ref:`own-mirrors <ref-classes-own-mirrors>` class, and use the - :term:`bitbake:BB_NO_NETWORK` + :term:`BB_NO_NETWORK` variable to your ``local.conf``. ::
@@ -4457,7 +4457,7 @@ variable for more information: - :term:`BB_NUMBER_THREADS`: The maximum number of threads BitBake simultaneously executes. -- :term:`bitbake:BB_NUMBER_PARSE_THREADS`: +- :term:`BB_NUMBER_PARSE_THREADS`: The number of threads BitBake uses during parsing. - :term:`PARALLEL_MAKE`: Extra
@@ -9121,7 +9121,7 @@ BitBake has determined by doing the following: The output of ``bitbake-dumpsig`` also includes the value each variable had, a list of dependencies for each variable, and - :term:`bitbake:BB_HASHBASE_WHITELIST` + :term:`BB_HASHBASE_WHITELIST` information. There is also a ``bitbake-diffsigs`` command for comparing two
documentation/migration-guides/migration-3.0.rst +1 -1
@@ -194,7 +194,7 @@ The following BitBake changes have occurred. scripts that handles these two events need to be updated. - The arguments passed to functions used with - :term:`bitbake:BB_HASHCHECK_FUNCTION` + :term:`BB_HASHCHECK_FUNCTION` have changed. If you are using your own custom hash check function, see :yocto_git:`/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725` for details.
documentation/overview-manual/concepts.rst +2 -4
@@ -1250,11 +1250,9 @@ download or setscene task fails, the build system then tries to install dependencies, such as the compiler, from the cache. The availability of objects in the sstate cache is handled by the -function specified by the -:term:`bitbake:BB_HASHCHECK_FUNCTION` +function specified by the :term:`BB_HASHCHECK_FUNCTION` variable and returns a list of available objects. The function specified -by the -:term:`bitbake:BB_SETSCENE_DEPVALID` +by the :term:`BB_SETSCENE_DEPVALID` variable is the function that determines whether a given dependency needs to be followed, and whether for any given relationship the function needs to be passed. The function returns a True or False value.
documentation/ref-manual/variables.rst +2 -3
@@ -762,8 +762,7 @@ system and gives an overview of their function and contents. export BBSERVER=localhost:$port - By default, :term:`BBSERVER` also appears in - :term:`bitbake:BB_HASHBASE_WHITELIST`. + By default, :term:`BBSERVER` also appears in :term:`BB_HASHBASE_WHITELIST`. Consequently, :term:`BBSERVER` is excluded from checksum and dependency data.
@@ -6500,7 +6499,7 @@ system and gives an overview of their function and contents. - :term:`CONF_VERSION` - :term:`BB_NUMBER_THREADS` - - :term:`bitbake:BB_NUMBER_PARSE_THREADS` + - :term:`BB_NUMBER_PARSE_THREADS` - :term:`PARALLEL_MAKE` - :term:`PRSERV_HOST` - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
Signature · 1 line
2.25.1
Hi Michael,
Quoted 10 lines · Michael Opdenacker
This new version:
- Updates the guidelines about refering to variable descriptions in the BitBake manual
- Explains the simplifications made to the references to the BitBake manual
- Add a new commit to replace explicit references to term descriptions in the BitBake manual by generic term references. Such descriptions are taken first from the Yocto Project Variable Glossary, or otherwise from the BitBake manual.
Quoted 2 lines
*** BLURB HERE ***
Adding my blurb then :)
Except for a small change in patch 2 of the series:
Thanks!
Quentin
Quoted 13 lines · Quentin Schulz
Hi Michael,
Quoted 10 lines · Michael Opdenacker
This new version:
- Updates the guidelines about refering to variable descriptions in the BitBake manual
- Explains the simplifications made to the references to the BitBake manual
- Add a new commit to replace explicit references to term descriptions in the BitBake manual by generic term references. Such descriptions are taken first from the Yocto Project Variable Glossary, or otherwise from the BitBake manual.
Quoted 3 lines
Quoted 2 lines
*** BLURB HERE ***
Adding my blurb then :)
Oops, that was embarrassing. Thanks for your blurb then!
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com