[PATCH] doc: build: docker: Fix code-block formatting

[PATCH] doc: build: docker: Fix code-block formatting

[Leonard Anderweit]

Remove double : before code-block. While at it, use code-block for all
bash commands.

Signed-off-by: Leonard Anderweit <l.anderweit@phytec.de>
---
 doc/build/docker.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/build/docker.rst b/doc/build/docker.rst
index 01ed35050908..4974a98d4af5 100644
--- a/doc/build/docker.rst
+++ b/doc/build/docker.rst
@@ -12,7 +12,9 @@ You will need a multi-platform container, otherwise this error is shown::
     ERROR: Multi-platform build is not supported for the docker driver.
     Switch to a different driver, or turn on the containerd image store, and try again.
 
-You can add a simple one with::
+You can add a simple one with:
+
+.. code-block:: bash
 
     sudo docker buildx create --name multiarch --driver docker-container --use
 
@@ -20,7 +22,9 @@ This will result in a builder that will use QEMU for the non-native
 architectures request in a build.  While both amd64 and arm64 happen in
 parallel, the non-native part will take considerably longer as it must use QEMU
 to emulate the foreign code.  An alternative, if you have accesss to reasonably
-fast amd64 (i.e. 64-bit x86) and arm64 machines is::
+fast amd64 (i.e. 64-bit x86) and arm64 machines is:
+
+.. code-block:: bash
 
     sudo docker buildx create --name multiarch-multinode --node localNode --bootstrap --use
     sudo docker buildx create --name multiarch-multinode --append --node remoteNode --bootstrap ssh://user@host
@@ -28,7 +32,7 @@ fast amd64 (i.e. 64-bit x86) and arm64 machines is::
 And this will result in a builder named multiarch-multinode that will build
 each platform natively on each node.
 
-To build the image yourself::
+To build the image yourself:
 
 .. code-block:: bash
 
-- 
2.34.1

Re: [PATCH] doc: build: docker: Fix code-block formatting

[Quentin Schulz]

Hi Leonard,

On 4/1/25 11:49 AM, Leonard Anderweit wrote:
> Remove double : before code-block. While at it, use code-block for all

Why?

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks 
is valid.

We could think about changing the default highlighting language to bash 
maybe, I don't know.

If you use ..code-block instead of :: for syntax highlighting, then say 
that in the commit log :)

Can be two commits though, one for fixing the :: following by a 
..code-block, and another one for switching the :: to ..code-block:: 
with syntax highlighting.

> bash commands.
> 
> Signed-off-by: Leonard Anderweit <l.anderweit@phytec.de>
> ---
>   doc/build/docker.rst | 10 +++++++---
>   1 file changed, 7 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/build/docker.rst b/doc/build/docker.rst
> index 01ed35050908..4974a98d4af5 100644
> --- a/doc/build/docker.rst
> +++ b/doc/build/docker.rst
> @@ -12,7 +12,9 @@ You will need a multi-platform container, otherwise this error is shown::
>       ERROR: Multi-platform build is not supported for the docker driver.
>       Switch to a different driver, or turn on the containerd image store, and try again.
>   
> -You can add a simple one with::
> +You can add a simple one with:
> +
> +.. code-block:: bash
>   
>       sudo docker buildx create --name multiarch --driver docker-container --use
>   
> @@ -20,7 +22,9 @@ This will result in a builder that will use QEMU for the non-native
>   architectures request in a build.  While both amd64 and arm64 happen in
>   parallel, the non-native part will take considerably longer as it must use QEMU
>   to emulate the foreign code.  An alternative, if you have accesss to reasonably
> -fast amd64 (i.e. 64-bit x86) and arm64 machines is::
> +fast amd64 (i.e. 64-bit x86) and arm64 machines is:
> +
> +.. code-block:: bash
>   
>       sudo docker buildx create --name multiarch-multinode --node localNode --bootstrap --use
>       sudo docker buildx create --name multiarch-multinode --append --node remoteNode --bootstrap ssh://user@host
> @@ -28,7 +32,7 @@ fast amd64 (i.e. 64-bit x86) and arm64 machines is::
>   And this will result in a builder named multiarch-multinode that will build
>   each platform natively on each node.
>   
> -To build the image yourself::
> +To build the image yourself:

This one change is fine though (or removing the next line).

>   
>   .. code-block:: bash
>   

Cheers,
Quentin

Re: [PATCH] doc: build: docker: Fix code-block formatting

[Leonard Anderweit]

Hi Quentin,

Am Dienstag, dem 01.04.2025 um 12:07 +0200 schrieb Quentin Schulz:
> Hi Leonard,
> 
> On 4/1/25 11:49 AM, Leonard Anderweit wrote:
> > Remove double : before code-block. While at it, use code-block for
> > all
> 
> Why?

I just found it odd that the two styles are mixed here.
> 
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
>  
> is valid.
> 
> We could think about changing the default highlighting language to
> bash 
> maybe, I don't know.
> 
> If you use ..code-block instead of :: for syntax highlighting, then
> say 
> that in the commit log :)
> 
> Can be two commits though, one for fixing the :: following by a 
> ..code-block, and another one for switching the :: to ..code-block:: 
> with syntax highlighting.

Ok, I'll split the changes into two commits.

Leonard
> 
> > bash commands.
> > 
> > Signed-off-by: Leonard Anderweit <l.anderweit@phytec.de>
> > ---
> >   doc/build/docker.rst | 10 +++++++---
> >   1 file changed, 7 insertions(+), 3 deletions(-)
> > 
> > diff --git a/doc/build/docker.rst b/doc/build/docker.rst
> > index 01ed35050908..4974a98d4af5 100644
> > --- a/doc/build/docker.rst
> > +++ b/doc/build/docker.rst
> > @@ -12,7 +12,9 @@ You will need a multi-platform container,
> > otherwise this error is shown::
> >       ERROR: Multi-platform build is not supported for the docker
> > driver.
> >       Switch to a different driver, or turn on the containerd image
> > store, and try again.
> >   
> > -You can add a simple one with::
> > +You can add a simple one with:
> > +
> > +.. code-block:: bash
> >   
> >       sudo docker buildx create --name multiarch --driver docker-
> > container --use
> >   
> > @@ -20,7 +22,9 @@ This will result in a builder that will use QEMU
> > for the non-native
> >   architectures request in a build.  While both amd64 and arm64
> > happen in
> >   parallel, the non-native part will take considerably longer as it
> > must use QEMU
> >   to emulate the foreign code.  An alternative, if you have accesss
> > to reasonably
> > -fast amd64 (i.e. 64-bit x86) and arm64 machines is::
> > +fast amd64 (i.e. 64-bit x86) and arm64 machines is:
> > +
> > +.. code-block:: bash
> >   
> >       sudo docker buildx create --name multiarch-multinode --node
> > localNode --bootstrap --use
> >       sudo docker buildx create --name multiarch-multinode --append
> > --node remoteNode --bootstrap ssh://user@host
> > @@ -28,7 +32,7 @@ fast amd64 (i.e. 64-bit x86) and arm64 machines
> > is::
> >   And this will result in a builder named multiarch-multinode that
> > will build
> >   each platform natively on each node.
> >   
> > -To build the image yourself::
> > +To build the image yourself:
> 
> This one change is fine though (or removing the next line).
> 
> >   
> >   .. code-block:: bash
> >   
> 
> Cheers,
> Quentin

Re: [PATCH] doc: build: docker: Fix code-block formatting

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 586 bytes --]

On Tue, Apr 01, 2025 at 11:18:45AM +0000, Leonard Anderweit wrote:
> Hi Quentin,
> 
> Am Dienstag, dem 01.04.2025 um 12:07 +0200 schrieb Quentin Schulz:
> > Hi Leonard,
> > 
> > On 4/1/25 11:49 AM, Leonard Anderweit wrote:
> > > Remove double : before code-block. While at it, use code-block for
> > > all
> > 
> > Why?
> 
> I just found it odd that the two styles are mixed here.

We're bad about consistency in things like this. I likely went with "::"
being the shortest way to get things looking OK but indeed a code-block
statement is correct. Thanks!

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]