| Message ID | 20251127-bitbake-setup-updates-v1-3-75ac1e490a40@bootlin.com |
|---|---|
| State | Accepted |
| Headers | show |
| Series | bitbake-setup updates | expand |
Hi Antonin, On 11/27/25 5:37 PM, Antonin Godard via lists.yoctoproject.org wrote: > Console outputs are more accurately represented with the 'console' > lexer. Visually, it separates the command from the output. Switch shell > block to console blocks. > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > --- > documentation/brief-yoctoprojectqs/index.rst | 36 ++++++++++++++-------------- > 1 file changed, 18 insertions(+), 18 deletions(-) > > diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst > index 1e0d867d6..b8bd65f4a 100644 > --- a/documentation/brief-yoctoprojectqs/index.rst > +++ b/documentation/brief-yoctoprojectqs/index.rst > @@ -95,13 +95,13 @@ get a copy of the ``bitbake-setup`` tool to setup the :term:`Poky` reference > distribution on your build host. Use the following commands to clone > the bitbake repository. > > -.. code-block:: shell > +.. code-block:: console > > $ git clone https://git.openembedded.org/bitbake > > Setup a build environment with the following command: > > -.. code-block:: shell > +.. code-block:: console > > $ ./bitbake/bin/bitbake-setup init > > @@ -110,7 +110,7 @@ By default, this will setup a top directory in the current directory. > If you prefer to setup your builds in a different top directory, for example > ``$HOME/bitbake-builds``, you can set it with the :ref:`bitbake:ref-bbsetup-command-settings` command: > > -.. code-block:: shell > +.. code-block:: console > > $ ./bitbake/bin/bitbake-setup settings set --global default top-dir-prefix $HOME > > @@ -125,7 +125,7 @@ differ from the examples below. > > #. Choose a configuration (for example, ``poky-master``): > > - .. code-block:: shell > + .. code-block:: console > Neither shell nor console. I would suggest to simply use a literal block (::), c.f. https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks > Available configurations: > 1. poky-master Poky - The Yocto Project testing distribution configurations and hardware test platforms > @@ -140,7 +140,7 @@ differ from the examples below. > Depending on the choice above, new options can be prompted to further specify > which configuration to use. For example: > > - .. code-block:: shell > + .. code-block:: console > Ditto. > Available bitbake configurations: > 1. poky Poky - The Yocto Project testing distribution > @@ -151,7 +151,7 @@ differ from the examples below. > > #. Choose a target :term:`MACHINE` (for example, ``qemux86-64``): > > - .. code-block:: shell > + .. code-block:: console > Ditto. > Target machines: > 1. machine/qemux86-64 > @@ -165,7 +165,7 @@ differ from the examples below. > > #. Choose a :term:`DISTRO` (for example, ``poky``): > > - .. code-block:: shell > + .. code-block:: console > Ditto. > Distribution configuration variants: > 1. distro/poky > @@ -177,7 +177,7 @@ differ from the examples below. > > #. Choose a :term:`bitbake:setup` directory name: > > - .. code-block:: shell > + .. code-block:: console > Ditto. Cheers, Quentin
Hi, On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote: [...] >> #. Choose a configuration (for example, ``poky-master``): >> >> - .. code-block:: shell >> + .. code-block:: console >> > > Neither shell nor console. I would suggest to simply use a literal block > (::), c.f. > https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks Thanks, I'll change that. I just noticed but I think the default lexer for literal blocks is Python unless you explicitly set it to something else in the global configuration[1]. I think it makes sense to change it to "text" as the rendering looks odd in most places where it thinks it's Python code, whereas most of the time it's either text snippets or bitbake assignments. Antonin
On Fri Nov 28, 2025 at 2:11 PM CET, Antonin Godard wrote: > Hi, > > On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote: > [...] >>> #. Choose a configuration (for example, ``poky-master``): >>> >>> - .. code-block:: shell >>> + .. code-block:: console >>> >> >> Neither shell nor console. I would suggest to simply use a literal block >> (::), c.f. >> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks > > Thanks, I'll change that. > > I just noticed but I think the default lexer for literal blocks is Python unless > you explicitly set it to something else in the global configuration[1]. I think > it makes sense to change it to "text" as the rendering looks odd in most places > where it thinks it's Python code, whereas most of the time it's either text > snippets or bitbake assignments. Forgot the link :) [1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks End of the paragraph: Code highlighting can be enabled for these literal blocks on a document-wide basis using the highlight directive and on a project-wide basis using the highlight_language configuration option. The code-block directive can be used to set highlighting on a block-by-block basis. Antonin
Hi Antonin, On 11/28/25 2:11 PM, Antonin Godard wrote: > Hi, > > On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote: > [...] >>> #. Choose a configuration (for example, ``poky-master``): >>> >>> - .. code-block:: shell >>> + .. code-block:: console >>> >> >> Neither shell nor console. I would suggest to simply use a literal block >> (::), c.f. >> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks > > Thanks, I'll change that. > > I just noticed but I think the default lexer for literal blocks is Python unless > you explicitly set it to something else in the global configuration[1]. I think Ah, and I had missed that. I changed it to shell for my company's user manuals but I didn't know it was Python by default (well some sort of Python). > it makes sense to change it to "text" as the rendering looks odd in most places > where it thinks it's Python code, whereas most of the time it's either text > snippets or bitbake assignments. > I would recommend picking a sensible default. Since there doesn't exist a BitBake lexer (and I don't see a MR for that in pygments) yet, I guess going for "text" or "none" will do. Good catch! This though will get rid of highlights where it is (to me) somewhat useful, see most blocks in https://docs.yoctoproject.org/ref-manual/variables.html. Maybe it isn't *that* worth it. Up to you. Cheers, Quentin
Hi, On Fri Nov 28, 2025 at 2:30 PM CET, Quentin Schulz wrote: > Hi Antonin, > > On 11/28/25 2:11 PM, Antonin Godard wrote: >> Hi, >> >> On Thu Nov 27, 2025 at 5:47 PM CET, Quentin Schulz via lists.yoctoproject.org wrote: >> [...] >>>> #. Choose a configuration (for example, ``poky-master``): >>>> >>>> - .. code-block:: shell >>>> + .. code-block:: console >>>> >>> >>> Neither shell nor console. I would suggest to simply use a literal block >>> (::), c.f. >>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks >> >> Thanks, I'll change that. >> >> I just noticed but I think the default lexer for literal blocks is Python unless >> you explicitly set it to something else in the global configuration[1]. I think > > Ah, and I had missed that. I changed it to shell for my company's user > manuals but I didn't know it was Python by default (well some sort of > Python). > >> it makes sense to change it to "text" as the rendering looks odd in most places >> where it thinks it's Python code, whereas most of the time it's either text >> snippets or bitbake assignments. >> > I would recommend picking a sensible default. Since there doesn't exist > a BitBake lexer (and I don't see a MR for that in pygments) yet, I guess > going for "text" or "none" will do. Good catch! > > This though will get rid of highlights where it is (to me) somewhat > useful, see most blocks in > https://docs.yoctoproject.org/ref-manual/variables.html. Maybe it isn't > *that* worth it. Up to you. Yes, re-reading some of the docs I also noticed it would get rid of some useful highlighting, so I think for text blocks we should use .. code-block:: text when we think about it. I'll use that for the quick start guide. Thanks! Antonin
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst index 1e0d867d6..b8bd65f4a 100644 --- a/documentation/brief-yoctoprojectqs/index.rst +++ b/documentation/brief-yoctoprojectqs/index.rst @@ -95,13 +95,13 @@ get a copy of the ``bitbake-setup`` tool to setup the :term:`Poky` reference distribution on your build host. Use the following commands to clone the bitbake repository. -.. code-block:: shell +.. code-block:: console $ git clone https://git.openembedded.org/bitbake Setup a build environment with the following command: -.. code-block:: shell +.. code-block:: console $ ./bitbake/bin/bitbake-setup init @@ -110,7 +110,7 @@ By default, this will setup a top directory in the current directory. If you prefer to setup your builds in a different top directory, for example ``$HOME/bitbake-builds``, you can set it with the :ref:`bitbake:ref-bbsetup-command-settings` command: -.. code-block:: shell +.. code-block:: console $ ./bitbake/bin/bitbake-setup settings set --global default top-dir-prefix $HOME @@ -125,7 +125,7 @@ differ from the examples below. #. Choose a configuration (for example, ``poky-master``): - .. code-block:: shell + .. code-block:: console Available configurations: 1. poky-master Poky - The Yocto Project testing distribution configurations and hardware test platforms @@ -140,7 +140,7 @@ differ from the examples below. Depending on the choice above, new options can be prompted to further specify which configuration to use. For example: - .. code-block:: shell + .. code-block:: console Available bitbake configurations: 1. poky Poky - The Yocto Project testing distribution @@ -151,7 +151,7 @@ differ from the examples below. #. Choose a target :term:`MACHINE` (for example, ``qemux86-64``): - .. code-block:: shell + .. code-block:: console Target machines: 1. machine/qemux86-64 @@ -165,7 +165,7 @@ differ from the examples below. #. Choose a :term:`DISTRO` (for example, ``poky``): - .. code-block:: shell + .. code-block:: console Distribution configuration variants: 1. distro/poky @@ -177,7 +177,7 @@ differ from the examples below. #. Choose a :term:`bitbake:setup` directory name: - .. code-block:: shell + .. code-block:: console Enter setup directory name: [poky-master-poky-distro_poky-machine_qemux86-64] @@ -189,7 +189,7 @@ differ from the examples below. If you prefer to run non-interactively, you can run a command like the following: - .. code-block:: shell + .. code-block:: console $ bitbake-setup init --non-interactive poky-master poky-with-sstate distro/poky machine/qemux86-64 @@ -248,7 +248,7 @@ an entire Linux distribution, including the toolchain, from source. environment setup script within the :term:`bitbake:BitBake build` directory to setup the :term:`BitBake` build environment on your host: - .. code-block:: shell + .. code-block:: console $ source poky-master-poky-distro_poky-machine_qemux86-64/build/init-build-env Poky reference distro build @@ -261,7 +261,7 @@ an entire Linux distribution, including the toolchain, from source. With this tool, list the currently enabled :term:`configuration fragments <Configuration Fragment>`: - .. code-block:: shell + .. code-block:: console $ bitbake-config-build list-fragments @@ -288,7 +288,7 @@ an entire Linux distribution, including the toolchain, from source. can be useful for development, you can enable the :ref:`ref-fragments-root-login-with-empty-password` fragment: - .. code-block:: shell + .. code-block:: console $ bitbake-config-build enable-fragment root-login-with-empty-password @@ -318,7 +318,7 @@ an entire Linux distribution, including the toolchain, from source. #. **Start the Build:** Continue with the following command to build an OS image for the target, which is ``core-image-sato`` in this example: - .. code-block:: shell + .. code-block:: console $ bitbake core-image-sato @@ -332,7 +332,7 @@ an entire Linux distribution, including the toolchain, from source. built, you can start QEMU, which is a Quick EMUlator that ships with the Yocto Project: - .. code-block:: shell + .. code-block:: console $ runqemu qemux86-64 @@ -378,7 +378,7 @@ layer>`: For this, the ``bitbake-layers add-layer`` can be used: - .. code-block:: shell + .. code-block:: console $ bitbake-layers add-layer ../layers/meta-raspberrypi @@ -393,7 +393,7 @@ layer>`: machine, so let's make it the :term:`MACHINE` used for the build with ``bitbake-config-build``: - .. code-block:: shell + .. code-block:: console $ bitbake-config-build enable-fragment machine/raspberrypi5 @@ -414,7 +414,7 @@ layer>`: #. **Start The Build:** The configuration is now set to build for the Raspberry Pi 5. Start the build again: - .. code-block:: shell + .. code-block:: console $ bitbake core-image-sato @@ -441,7 +441,7 @@ configuration file, a ``recipes-example`` subdirectory that contains an The following commands run the tool to create a layer named ``meta-mylayer``: -.. code-block:: shell +.. code-block:: console $ bitbake-layers create-layer ../layers/meta-mylayer NOTE: Starting bitbake server...
Console outputs are more accurately represented with the 'console' lexer. Visually, it separates the command from the output. Switch shell block to console blocks. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/brief-yoctoprojectqs/index.rst | 36 ++++++++++++++-------------- 1 file changed, 18 insertions(+), 18 deletions(-)