doc: west: add examples for each topology

Add example west.yml files showing how to build west workspaces of
each type. Split these into separate sections as a result since
they're longer.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

doc/guides/west/repo-tool.rst

@@ -78,70 +78,166 @@ repository.
 Topologies supported
 ********************
 
-The following three source code topologies supported by west:
+The following are example source code topologies supported by west.
 
-* **T1**: Star topology with zephyr as the manifest repository:
+- T1: star topology, zephyr is the manifest repository
+- T2: star topology, a Zephyr application is the manifest repository
+- T3: forest topology, freestanding manifest repository
 
-  - The zephyr repository acts as the central repository and includes a
-    complete list of projects used upstream
-  - Default (upstream) configuration
-  - Analogy with existing mechanisms: Git sub-modules with zephyr as the
-    super-project
-  - See :ref:`west-installation` for how mainline Zephyr is an example
-    of this topology
+T1: Star topology, zephyr is the manifest repository
+====================================================
 
-* **T2**: Star topology with an application repository as the manifest
-  repository:
+- The zephyr repository acts as the central repository and specifies
+  its :ref:`modules` in its :file:`west.yml`
+- Analogy with existing mechanisms: Git submodules with zephyr as the
+  super-project
 
-  - A repository containing a Zephyr application acts as the central repository
-    and includes a complete list of other projects, including the zephyr
-    repository, required to build it
-  - Useful for those focused on a single application
-  - Analogy with existing mechanisms: Git sub-modules with the application as
-    the super-project, zephyr and other projects as sub-modules
-  - An installation using this topology could look like this:
+This is the default. See :ref:`west-installation` for how mainline Zephyr is an
+example of this topology.
 
-    .. code-block:: none
+.. _west-t2:
 
-       app-manifest-installation
-       ├── application
-       │   ├── CMakeLists.txt
-       │   ├── prj.conf
-       │   ├── src
-       │   │   └── main.c
-       │   └── west.yml
-       ├── modules
-       │   └── lib
-       │       └── tinycbor
-       └── zephyr
+T2: Star topology, application is the manifest repository
+=========================================================
 
-* **T3**: Forest topology:
+- Useful for those focused on a single application
+- A repository containing a Zephyr application acts as the central repository
+  and names other projects required to build it in its :file:`west.yml`. This
+  includes the zephyr repository and any modules.
+- Analogy with existing mechanisms: Git submodules with the application as
+  the super-project, zephyr and other projects as submodules
 
-  - A dedicated manifest repository which contains no Zephyr source code,
-    and specifies a list of projects all at the same "level"
-  - Useful for downstream distributions with no "central" repository
-  - Analogy with existing mechanisms: Google repo-based source distribution
-  - An installation using this topology could look like this:
+An installation using this topology looks like this:
 
-    .. code-block:: none
+.. code-block:: none
 
-       forest
-       ├── app1
-       │   ├── CMakeLists.txt
-       │   ├── prj.conf
-       │   └── src
-       │       └── main.c
-       ├── app2
-       │   ├── CMakeLists.txt
-       │   ├── prj.conf
-       │   └── src
-       │       └── main.c
-       ├── manifest-repo
-       │   └── west.yml
-       ├── modules
-       │   └── lib
-       │       └── tinycbor
-       └── zephyr
+   west-workspace
+   ├── application
+   │   ├── CMakeLists.txt
+   │   ├── prj.conf
+   │   ├── src
+   │   │   └── main.c
+   │   └── west.yml
+   ├── modules
+   │   └── lib
+   │       └── tinycbor
+   └── zephyr
+
+Here is an example :file:`application/west.yml` which uses
+:ref:`west-manifest-import`, available since west 0.7, to import Zephyr v2.2.0
+and its modules into the application manifest file:
+
+.. code-block:: yaml
+
+   # Example T2 west.yml, using manifest imports.
+   manifest:
+     remotes:
+       - name: zephyrproject-rtos
+         url-base: https://github.com/zephyrproject-rtos
+     projects:
+       - name: zephyr
+         remote: zephyrproject-rtos
+         revision: v2.2.0
+         import: true
+     self:
+       path: application
+
+You can still selectively "override" individual Zephyr modules if you use
+``import:`` in this way; see :ref:`west-manifest-ex1.3` for an example.
+
+Another way to do the same thing is to copy/paste :file:`zephyr/west.yml`
+to :file:`application/west.yml`, adding an entry for the zephyr
+project itself, like this:
+
+.. code-block:: yaml
+
+   # Equivalent to the above, but with manually maintained Zephyr modules.
+   manifest:
+     remotes:
+       - name: zephyrproject-rtos
+         url-base: https://github.com/zephyrproject-rtos
+     defaults:
+       remote: zephyrproject-rtos
+     projects:
+       - name: zephyr
+         revision: v2.2.0
+         west-commands: scripts/west-commands.yml
+       - name: net-tools
+         revision: some-sha-goes-here
+         path: tools/net-tools
+       # ... other Zephyr modules go here ...
+     self:
+       path: application
+
+(The ``west-commands`` is there for :ref:`west-build-flash-debug` and other
+Zephyr-specific :ref:`west-extensions`. It's not necessary when using
+``import``.)
+
+The main advantage to using ``import`` is not having to track the revisions of
+imported projects separately. In the above example, using ``import`` means
+Zephyr's :ref:`module <modules>` versions are automatically determined from the
+:file:`zephyr/west.yml` revision, instead of having to be copy/pasted (and
+maintained) on their own.
+
+T3: Forest topology
+===================
+
+- Useful for those supporting multiple independent applications or downstream
+  distributions with no "central" repository
+- A dedicated manifest repository which contains no Zephyr source code,
+  and specifies a list of projects all at the same "level"
+- Analogy with existing mechanisms: Google repo-based source distribution
+
+An installation using this topology looks like this:
+
+.. code-block:: none
+
+   west-workspace
+   ├── app1
+   │   ├── CMakeLists.txt
+   │   ├── prj.conf
+   │   └── src
+   │       └── main.c
+   ├── app2
+   │   ├── CMakeLists.txt
+   │   ├── prj.conf
+   │   └── src
+   │       └── main.c
+   ├── manifest-repo
+   │   └── west.yml
+   ├── modules
+   │   └── lib
+   │       └── tinycbor
+   └── zephyr
+
+Here is an example T3 :file:`manifest-repo/west.yml` which uses
+:ref:`west-manifest-import`, available since west 0.7, to import Zephyr
+v2.2.0 and its modules, then add the ``app1`` and ``app2`` projects:
+
+.. code-block:: yaml
+
+   manifest:
+     remotes:
+       - name: zephyrproject-rtos
+         url-base: https://github.com/zephyrproject-rtos
+       - name: your-git-server
+         url-base: https://git.example.com/your-company
+     defaults:
+       remote: your-git-server
+     projects:
+       - name: zephyr
+         remote: zephyrproject-rtos
+         revision: v2.2.0
+         import: true
+       - name: app1
+         revision: SOME_SHA_OR_BRANCH_OR_TAG
+       - name: app2
+         revision: ANOTHER_SHA_OR_BRANCH_OR_TAG
+     self:
+       path: manifest-repo
+
+You can also do this "by hand" by copy/pasting :file:`zephyr/west.yml`
+as shown :ref:`above <west-t2>` for the T2 topology, with the same caveats.
 
 .. _west-struct: