Skip to contentSkip to conversation

doc: build: docker: Fix code-block formatting

PATCH In review Leonard Anderweit 3 participants 4 messages Apr 1, 2025

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: build: docker: Fix code-block formatting

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

---
 doc/build/docker.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
doc/build/docker.rst +7 -3
index 01ed35050908..4974a98d4af5 100644
@@ -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
 
Signature · 1 line
2.34.1
#1 lore raw

Hi Leonard,

Quoted 1 line · Leonard Anderweit

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.

Quoted 34 lines

bash commands.

---
  doc/build/docker.rst | 10 +++++++---
  1 file changed, 7 insertions(+), 3 deletions(-)
doc/build/docker.rst +6 -2
index 01ed35050908..4974a98d4af5 100644
@@ -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

doc/build/docker.rst fast amd64 (i.e. 64-bit x86) and arm64 machines is:: · line 35

Quoted 5 lines
doc/build/docker.rst +1 -1
@@ -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).

doc/build/docker.rst fast amd64 (i.e. 64-bit x86) and arm64 machines is:: · line 38

Quoted 3 lines
doc/build/docker.rst +0 -0
  .. code-block:: bash
 

Cheers,
Quentin

#2 lore raw

Hi Quentin,

Am Dienstag, dem 01.04.2025 um 12:07 +0200 schrieb Quentin Schulz:

Quoted 7 lines

Hi Leonard,

Quoted 2 lines · Leonard Anderweit

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.

Quoted 9 lines

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.

Quoted 7 lines

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

Quoted 61 lines
Quoted 50 lines

bash commands.

---
  doc/build/docker.rst | 10 +++++++---

  1 file changed, 7 insertions(+), 3 deletions(-)
doc/build/docker.rst +0 -0
index 01ed35050908..4974a98d4af5 100644
@@ -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.

doc/build/docker.rst +3 -1
-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

doc/build/docker.rst +0 -0
@@ -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

doc/build/docker.rst +3 -1
-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

doc/build/docker.rst +0 -0
@@ -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.

doc/build/docker.rst fast amd64 (i.e. 64-bit x86) and arm64 machines is:: · line 35

Quoted 2 lines
doc/build/docker.rst +1 -1
-To build the image yourself::
+To build the image yourself:

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

Quoted 3 lines


  .. code-block:: bash

Cheers,
Quentin

#3 lore raw
Quoted 5 lines · Leonard Anderweit

Hi Quentin,

Am Dienstag, dem 01.04.2025 um 12:07 +0200 schrieb Quentin Schulz:

Quoted 2 lines

Hi Leonard,

Quoted 7 lines
Quoted 5 lines · Leonard Anderweit
Quoted 2 lines

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!

Signature · 1 line
Tom