From ea98db0b1dcddf4d68755449fc112d84770e02e0 Mon Sep 17 00:00:00 2001
From: Hugo Osvaldo Barrera <hugo@whynothugo.nl>
Date: Wed, 23 Jul 2025 17:29:58 +0200
Subject: docs: shuffle sections into logical order

The first section explains how to clone the repository, the second how
to build Infinitime with the docker image, but the details on actually
provisioning the image are at the end, despite this step taking place
before the build itself.

Move the sections into the order in which the steps should be followed.
---
 doc/buildWithDocker.md | 64 +++++++++++++++++++++++++++-----------------------
 1 file changed, 35 insertions(+), 29 deletions(-)

diff --git a/doc/buildWithDocker.md b/doc/buildWithDocker.md
index 670590a6..9d4db707 100644
--- a/doc/buildWithDocker.md
+++ b/doc/buildWithDocker.md
@@ -15,46 +15,37 @@ Based on Ubuntu 22.04 with the following build dependencies:
 
 Before building, local repository must be fully initialized.
 
-```
+```sh
 git clone https://github.com/InfiniTimeOrg/InfiniTime.git
 cd InfiniTime
 git submodule update --init
 ```
 
-## Run a container to build the project
-
-The `infinitime-build` image contains all the dependencies you need.
-The default `CMD` will compile sources found in `/sources`, so you need only mount your code.
-
-Before continuing, make sure you first build the image as indicated in the [Build the image](#build-the-image) section, or check the [Using the image from Docker Hub](#using-the-image-from-docker-hub) section if you prefer to use a pre-made image.
+## Provision the image
 
-This example will build the firmware, generate the MCUBoot image and generate the DFU file.
-For cloning the repo, see [these instructions](../doc/buildAndProgram.md#clone-the-repo). Outputs will be written to **<project_root>/build/output**:
+Before continuing, the build image needs to be either build locally or pulled
+from Docker Hub, as described in the two sections below:
 
-```bash
-cd <project_root> # e.g. cd ./work/Pinetime
-docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build
-```
+### Build the image
 
-By default, the container runs as `root`, which is not convenient as all the files generated by the build will also belong to `root`.
-The parameter `--user` overrides that default behavior.
-The command above will run as your current user.
+You can build the image yourself if you like!
 
-If you only want to build a single CMake target, you can pass it in as the first parameter to the build script.
-This means calling the script explicitly as it will override the `CMD`.
-Here's an example for `pinetime-app`:
+The following commands must be run from the root of the project. This operation
+will take some time but, when done, a new image named `infinitime-build` is
+available.
 
-```bash
-docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build /opt/build.sh pinetime-app
+```sh
+docker build -t infinitime-build ./docker
 ```
 
-## Using the image from Docker Hub
+### Pull the image from Docker Hub
 
-The image is available via Docker Hub for both the amd64 and arm64v8 architectures at [infinitime/infinitime-build](https://hub.docker.com/repository/docker/infinitime/infinitime-build).
+The image is available via Docker Hub for both the amd64 and arm64v8 architectures at
+[infinitime/infinitime-build](https://hub.docker.com/repository/docker/infinitime/infinitime-build).
 
 You can run it using the following command:
 
-```bash
+```sh
 docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime/infinitime-build
 ```
 
@@ -64,12 +55,27 @@ The default `latest` tag *should* automatically identify the correct image archi
 
 - For ARM64v8 (ARM64/aarch64) systems: `docker pull --platform linux/arm64 infinitime/infinitime-build`
 
-## Build the image
+## Run a container to build the project
 
-You can build the image yourself if you like!
+The `infinitime-build` image contains all the dependencies you need.
+The default `CMD` will compile sources found in `/sources`, so you need only mount your code.
 
-The following commands must be run from the root of the project. This operation will take some time but, when done, a new image named *infinitime-build* is available.
+This example will build the firmware, generate the MCUBoot image and generate the DFU file.
+For cloning the repo, see [these instructions](../doc/buildAndProgram.md#clone-the-repo). Outputs will be written to **<project_root>/build/output**:
 
-```bash
-docker build -t infinitime-build ./docker
+```sh
+cd <project_root> # e.g. cd ./work/Pinetime
+docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build
+```
+
+By default, the container runs as `root`, which is not convenient as all the files generated by the build will also belong to `root`.
+The parameter `--user` overrides that default behavior.
+The command above will run as your current user.
+
+If you only want to build a single CMake target, you can pass it in as the first parameter to the build script.
+This means calling the script explicitly as it will override the `CMD`.
+Here's an example for `pinetime-app`:
+
+```sh
+docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build /opt/build.sh pinetime-app
 ```
-- 
cgit v1.2.3-70-g09d2