Minor documentation tweaks

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.
+## Provision the image
 
-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.
+Before continuing, the build image needs to be either build locally or pulled
+from Docker Hub, as described in the two sections below:
 
-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
-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,35 @@ 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.
+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 infinitime-build
+```
+
+If the docker service is running as `root`, the build process inside the
+container also runs as `root`, which is not convenient as all the files
+generated by the build will also belong to `root`. The parameter `--user`
+overrides this behaviour. The command below ensures that all files are created
+as your current user:
+
+
+```sh
+cd <project_root> # e.g. cd ./work/Pinetime
+docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build
+```
+
+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
 ```

docker/Dockerfile

@@ -68,5 +68,5 @@ RUN adduser infinitime
 # Configure Git to accept the /sources directory as safe
 RUN git config --global --add safe.directory /sources
 
-ENV SOURCES_DIR /sources
+ENV SOURCES_DIR=/sources
 CMD ["/opt/build.sh"]