Edit the topic so it looks like a task. Minor corrections to commands and links.

Author: anton-intel

getting_started/build-guide/build-from-scratch.rst

@@ -347,6 +347,8 @@ This should take a few minutes.
 The required headers are now in ``"$SOF_WORKSPACE"/xtensa-root``, and
 cross-compilation toolchains for xtensa DSPs are set up.
 
+.. _build-and-sign-firmware-binaries-from-scratch:
+
 Step 4. Build and sign firmware binaries
 ****************************************
 
@@ -510,6 +512,7 @@ folder.
 
    sof-apl.ri  sof-bdw.ri  sof-byt.ri  sof-cht.ri  sof-cnl.ri  sof-hsw.ri
 
+.. _build-topology-and-tools-from-scratch:
 
 Step 5. Build topology and tools
 ********************************

getting_started/build-guide/build-with-docker.rst

@@ -10,123 +10,113 @@ Build SOF with Docker
 This guide will show you how to use a Docker image containing the
 |SOF| build environment. 
 
-.. note::
-
-        The example uses ``$SOF_WORKSPACE`` as the working directory.
-
 Set up the workspace directory
 ******************************
 
-  .. code-block:: bash
+1. Point the ``$SOF_WORKSPACE`` environment variable to the directory
+   in which you store all SOF work.
 
-     SOF_WORKSPACE=~/work/sof
-     mkdir "$SOF_WORKSPACE"
+   .. code-block:: bash
 
-Clone the *sof* repo.
+      SOF_WORKSPACE=~/work/sof
+      mkdir -p "$SOF_WORKSPACE"
 
-.. code-block:: bash
+#. Clone the SOF repository.
+
+   .. code-block:: bash
 
-   cd "$SOF_WORKSPACE"
-   git clone --recurse-submodules https://github.com/thesofproject/sof.git
+      cd "$SOF_WORKSPACE"
+      git clone --recurse-submodules https://github.com/thesofproject/sof.git
 
 Set up Docker
 *************
 
-Docker is a popular container management framework. To install on Ubuntu,
-visit `Get Docker CE for Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/>`__.
+Docker is a popular container management framework. To install Docker and get the Docker image with the SOF build environment:
 
-Installation instructions for other Linux distributions: `About Docker CE <https://docs.docker.com/install/>`__.
+1. Install Docker.
 
-Set Proxy
-=========
+   For information on how to install Docker on Ubuntu, visit `Install
+   Docker Engine on Ubuntu
+   <https://docs.docker.com/engine/install/ubuntu/>`__.
 
-Docker must be configured if used behind a proxy. 
-Visit `HTTP/HTTPS proxy <https://docs.docker.com/config/daemon/systemd/#httphttps-proxy>`__ for the guide.
+   For information on how to install Docker on other Linux
+   distributions, visit `Install Docker Engine
+   <https://docs.docker.com/engine/install/>`__.
 
-Set user group
-==============
+#. Optionally, configure Docker to run under a proxy.
 
-To use Docker without ``sudo`` follow these post-install steps.
-`Post-installation steps for Linux <https://docs.docker.com/install/linux/linux-postinstall/>`__
+   For more information about configuring Docker to use a proxy, visit
+   `HTTP/HTTPS proxy
+   <https://docs.docker.com/config/daemon/systemd/#httphttps-proxy>`__.
 
-Get Docker image
-================
+#. To use Docker without ``sudo``, add your user to the `docker` group.
 
-To easily build SOF binaries, we need a Docker image containing all
-of the cross-compiler and build environment dependencies. We can either
-build a Docker image from a DockerFile or pull an image binary from
-Docker Hub.
+   For more information, visit 
+   `Post-installation steps for Linux <https://docs.docker.com/install/linux/linux-postinstall/>`__.
 
-.. note::
-
-        Building the container from DockerFile will take more than 2 hours,
-        so we recommend using the pre-built image.
+#. Get a Docker image with the SOF build environment.
 
-Pull Docker image
------------------
+   To easily build SOF binaries, we need a Docker image containing all
+   of the cross-compiler and build environment dependencies. We can
+   either build a Docker image from a DockerFile or pull an image
+   binary from Docker Hub.
 
-Pull the docker image from Docker Hub.
+   .. note::
 
-.. code-block:: bash
-
-   docker pull thesofproject/sof
-
-.. note::
-
-        Since there is not yet an offical |SOF| presence on Dockerhub, the
-        image is hosted in a personal Docker Hub repo until the 
-        official image can go live.
+        Building the container from DockerFile will take more than 2 hours,
+        so we recommend using the pre-built image.
 
-Retag the image with `sof` for scripts.
+   - Pull the Docker image from Docker Hub and retag the image with `sof` for scripts:
 
-.. code-block:: bash
+     .. code-block:: bash
 
-   docker tag thesofproject/sof sof
+	docker pull thesofproject/sof
+	docker tag thesofproject/sof sof
 
+     .. note::
 
-Build Docker image
-------------------
+	Since there is not yet an offical |SOF| presence on
+        Dockerhub, the image is hosted in a personal Docker Hub repo
+        until the official image can go live.
 
-Run the Docker build from the `sof` repo.
+   - Build a Docker image:
 
-.. code-block:: bash
+     Run the Docker build from the SOF repository.
 
-   cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_qemu
-   ./docker-build.sh
-   cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_builder
-   ./docker-build.sh
+     .. code-block:: bash
 
-After building the Docker image you will see:
+	cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_qemu
+	./docker-build.sh
+	cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_builder
+	./docker-build.sh
 
-.. code-block:: bash
+     Verify that the docker image is built successfully.
 
-   docker images
-   #REPOSITORY             TAG                 IMAGE ID            CREATED             SIZE
-   #sof                    latest              c8b0e8913fcb        2 days ago          1.46 GB
+     .. code-block:: bash
 
-Build with Docker
-*****************
+	docker images
+	 
+	#REPOSITORY             TAG                 IMAGE ID            CREATED             SIZE
+	#sof                    latest              c8b0e8913fcb        2 days ago          1.46 GB
 
-Build firmware binaries
-=======================
+Build firmware binaries with Docker
+***********************************
 
 Build with scripts
-------------------
+==================
 
-Build the SOF binaries:
+To build the SOF binaries for all platforms:
 
 .. code-block:: bash
 
    cd "${SOF_WORKSPACE}"/sof/
-   ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh
-
-.. note::
+   ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh -a
 
-   ./scripts/docker-run.sh will mount the *sof* and directories
-   into Docker container and build them inside the container. The build
-   result can be accessed outside the container after the build.
+``./scripts/docker-run.sh`` mounts the *sof* and directories into the
+Docker container and builds them inside the container. You can access
+the build result outside the container after the build.
 
-Build one or more platform binaries.
+To build the SOF binaries for one or more platforms:
 
 .. code-block:: bash
 
@@ -137,65 +127,66 @@ Build one or more platform binaries.
    ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh byt apl
 
 Build inside container
-----------------------
+======================
 
-Enter the container bash.
+1. Enter the container bash:
 
-.. code-block:: bash
+   .. code-block:: bash
 
-   cd "${SOF_WORKSPACE}"/sof/
-   ./scripts/docker-run.sh bash
+      cd "${SOF_WORKSPACE}"/sof/
+      ./scripts/docker-run.sh bash
 
-From inside the container, follow the manual configuration and build steps.
+#. From inside the container, follow the manual configuration and build
+   steps. For more information, see
+   :ref:`build-and-sign-firmware-binaries-from-scratch`.
 
 Firmware build results
-----------------------
+======================
 
-The firmware binary files are located in src/arch/xtensa/. Copy them to
-your target machine's /lib/firmware/intel/sof folder.
+The firmware binary files are located in the
+``build_<platform>/src/arch/xtensa/`` directory. Copy them to the
+``/lib/firmware/intel/sof`` directory on the target machine.
 
 .. code-block:: bash
 
    sof-apl.ri  sof-bdw.ri  sof-byt.ri  sof-cht.ri  sof-cnl.ri  sof-hsw.ri
 
 .. _docker-topology-tools:
 
-Build topology and tools
-========================
+Build topology and tools with Docker
+************************************
 
 Build with scripts
-------------------
+==================
 
-Build the *sof* tools and topology files.
+Build the SOF tools and topology files.
 
 .. code-block:: bash
 
    cd "${SOF_WORKSPACE}"/sof/
    ./scripts/docker-run.sh ./scripts/build-tools.sh
 
 Build inside container
-----------------------
-
-Enter the container bash.
+======================
 
-.. code-block:: bash
-
-   cd "${SOF_WORKSPACE}"/sof/
-   ./scripts/docker-run.sh bash
-
-From inside the container:
-
-.. code-block:: bash
+1. Enter the container bash:
 
-   cd tools
+   .. code-block:: bash
+      
+      cd "${SOF_WORKSPACE}"/sof/
+      ./scripts/docker-run.sh bash
 
-and follow the manual configuration and build steps.
+2. From inside the container, change to the ``tools`` directory and
+   follow the manual configuration and build steps. For more
+   information, see :ref:`build-topology-and-tools-from-scratch`.
 
 Topology and tools build results
---------------------------------
+================================
 
-The topology files are all in the topology folder ("${SOF_WORKSPACE}"/sof/tools/build_tools/topology). Copy them to the target
-machine's /lib/firmware/intel/sof-tplg folder. 
+The topology files are located in the
+``"$SOF_WORKSPACE"/sof/tools/build_tools/topology`` folder. Copy the
+files to the ``/lib/firmware/intel/sof-tplg`` directory on the target
+machine.
 
-The *sof-logger* tool is in the *tools/logger* folder. Copy it to the target machine's
-/usr/bin directory.
+The *sof-logger* tool is located in the ``tools/logger`` directory. Copy
+it to the ``/usr/bin`` directory on the target machine.