documentation/README: improve BitBake manual referencing guidelines
PATCH 1/2 documentation/README: improve BitBake manual referencing guidelines
--- documentation/README | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)
documentation/README +8 -4
@@ -328,11 +328,15 @@ 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: - - See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option -or +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 + - With a BitBake variable name: :term:`bitbake:BB_NUMBER_PARSE_THREADS` + - Linking to the entire BitBake manual: + :doc:`BitBake User Manual <bitbake:index>` Submitting documentation changes ================================
Signature · 1 line
2.25.1
PATCH 2/2 manuals: simplify references to BitBake manual
--- 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
Hi Michael,
Quoted 14 lines · Michael Opdenacker
Signed-off-by Michael Opdenacker <[email protected]>--- documentation/README | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)documentation/README +0
-1@@ -328,11 +328,15 @@ 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:
documentation/README The sphinx.ext.intersphinx extension is enabled by default · line 337
Quoted 10 lines
documentation/README +6
-3- - See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option -or +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 + - With a BitBake variable name: :term:`bitbake:BB_NUMBER_PARSE_THREADS`
I'd rather not specify bitbake: for terms so that they can be overriden from within yocto-docs if need be, without needing to modify all the refs spread over the whole git repo.
Cheers,
Quentin
Hi Quentin,
Quoted 16 lines · Quentin Schulz
Hi Michael,
Quoted 13 lines · Michael Opdenacker
Signed-off-by Michael Opdenacker <[email protected]>--- documentation/README | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)documentation/README +0
-0@@ -328,11 +328,15 @@ 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.
Quoted 14 lines
documentation/README The sphinx.ext.intersphinx extension is enabled by default · line 337
Quoted 11 lines
documentation/README +6
-4-References to the bitbake manual can be done like this: - - See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option -or +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 + - With a BitBake variable name: :term:`bitbake:BB_NUMBER_PARSE_THREADS`I'd rather not specify bitbake: for terms so that they can be overriden from within yocto-docs if need be, without needing to modify all the refs spread over the whole git repo.
Thanks for the feedback. However, I'm not sure what you mean here... Do you mean we should replace all instances of ":term:bitbake:VARIABLE" by ":term:VARIABLE"?
If I understand well, if VARIABLE is only defined in the BitBake manual, we will directly get a reference in that manual.
Cheers,
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Quoted 35 lines · Michael Opdenacker
Hi Quentin,
Quoted 8 lines · Quentin Schulz
Hi Michael,
Quoted 5 lines · Michael Opdenacker
Signed-off-by Michael Opdenacker <[email protected]>--- documentation/README | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-)Quoted 5 lines
documentation/README The sphinx.ext.intersphinx extension is enabled
Quoted 5 lines
documentation/README +0
-0@@ -328,11 +328,15 @@ The sphinx.ext.intersphinx extension is enabledby default
Quoted 6 lines
documentation/README The sphinx.ext.intersphinx extension is enabled by default
Quoted 6 lines
documentation/README +0
-3so 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: - - See the ":ref:`-D<bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
Quoted 4 lines
documentation/README The sphinx.ext.intersphinx extension is enabled by default
Quoted 4 lines
documentation/README +3
-1-or +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>`
Quoted 2 lines
documentation/README The sphinx.ext.intersphinx extension is enabled · line 335
Quoted 2 lines
documentation/README +2
-0+ - With the section name: + ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usageand syntax` option
Quoted 2 lines
Quoted 2 lines
documentation/README +1
-0+ - With a BitBake variable name: :term:`bitbake:BB_NUMBER_PARSE_THREADS`
Quoted 9 lines
Quoted 3 lines
I'd rather not specify bitbake: for terms so that they can be overriden from within yocto-docs if need be, without needing to modify all the refs spread over the whole git repo.
Thanks for the feedback. However, I'm not sure what you mean here... Do you mean we should replace all instances of ":term:
bitbake:VARIABLE" by ":term:VARIABLE"?
Yes. I think we already discussed that. I initially didn't like the idea, but Quentin convinced me ;)
Quoted 4 lines
If I understand well, if VARIABLE is only defined in the BitBake manual, we will directly get a reference in that manual.
When using :term:FOO, if FOO is defined in bitbake only, then the link will be to the bitbake manual. If defined in both bitbake and yp-docs, then it will link to yp-docs instead. Which is most likely what we always want to do , if we ever need to override a term in yp-docs.
Quoted 12 lines
Cheers,
Michael.--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
Hi Nicolas,
Quoted 66 lines · Nicolas Dechesne
On Tue, Jul 27, 2021 at 4:29 PM Michael Opdenacker <[email protected] <mailto:[email protected]>> wrote:
Hi Quentin,
On 7/27/21 4:14 PM, Quentin Schulz wrote:
> Hi Michael,
>
> On Tue, Jul 27, 2021 at 04:11:59PM +0200, Michael Opdenacker wrote:
>> Signed-off-by: Michael Opdenacker <[email protected] <mailto:[email protected]>>
>> ---
>> documentation/README | 12 ++++++++----
>> 1 file changed, 8 insertions(+), 4 deletions(-)
>>
>> diff --git a/documentation/README b/documentation/README >> indexf9e803a28b..1d4d213076100644
>> --- a/documentation/README
>> +++ b/documentation/README
>> @@ -328,11 +328,15 @@ 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:
>> -
>> - See the ":ref:-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>" option
>> -or
>> +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 syntaxoption
>> + - With a BitBake variable name:
>> :term:bitbake:BB_NUMBER_PARSE_THREADS
> I'd rather not specify bitbake: for terms so that they can be overriden
> from within yocto-docs if need be, without needing to modify all the > refs spread over the whole git repo.Thanks for the feedback. However, I'm not sure what you mean here... Do
you mean we should replace all instances of ":term:bitbake:VARIABLE" by ":term:VARIABLE"?Yes. I think we already discussed that. I initially didn't like the idea, but Quentin convinced me ;)
If I understand well, if VARIABLE is only defined in the BitBake manual,
we will directly get a reference in that manual.
Quoted 5 lines
When using :term:
FOO, if FOO is defined in bitbake only, then the link will be to the bitbake manual. If defined in both bitbake and yp-docs, then it will link to yp-docs instead. Which is most likely what we always want to do , if we ever need to override a term in yp-docs.
Understood, I'll post an update that removes the explicit references to the BitBake variables, but I'll still document how to make such a reference, in case the needs arises one day.
Thanks!
Michael.
Signature · 3 lines
Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com