doc: west: add tl;dr for moving to west and troubleshooting

These are based on user feedback on slack and the mailing list.

Signed-off-by: Marti Bolivar <[email protected]>

Author: mbolivar-nordic

doc/guides/west/index.rst

@@ -34,6 +34,8 @@ context about the tool.
    :maxdepth: 1
 
    install.rst
+   moving-to-west.rst
+   troubleshooting.rst
    repo-tool.rst
    manifest.rst
    config.rst

doc/guides/west/moving-to-west.rst

@@ -0,0 +1,57 @@
+.. _moving-to-west:
+
+Moving to West
+##############
+
+To convert a "pre-west" Zephyr setup on your computer to west, follow these
+steps. If you are starting from scratch, use the :ref:`getting_started`
+instead. See :ref:`west-troubleshooting` for advice on common issues.
+
+#. Install west.
+
+   On Linux::
+
+     pip3 install --user -U west
+
+   On Windows and macOS::
+
+     pip3 install -U west
+
+   For details, see :ref:`west-install`.
+
+#. Move your zephyr repository to a new :file:`zephyrproject` parent directory,
+   and change directory there.
+
+   On Linux and macOS::
+
+     mkdir zephyrproject
+     mv zephyr zephyrproject
+     cd zephyrproject
+
+   On Windows ``cmd.exe``::
+
+     mkdir zephyrproject
+     move zephyr zephyrproject
+     chdir zephyrproject
+
+   The name :file:`zephyrproject` is recommended, but you can choose any name
+   with no spaces anywhere in the path.
+
+#. Create a :ref:`west installation <west-installation>` using the zephyr
+   repository as a local manifest repository::
+
+     west init -l zephyr
+
+   This creates :file:`zephyrproject/.west`, marking the root of your
+   installation, and does some other setup. It will not change the contents of
+   the zephyr repository in any way.
+
+#. Clone the rest of the repositories used by zephyr::
+
+     west update
+
+   **Make sure to run this command whenever you pull zephyr.** Otherwise, your
+   local repositories will get out of sync. (Run ``west list`` for current
+   information on these repositories.)
+
+You are done: :file:`zephyrproject` is now set up to use west.

doc/guides/west/troubleshooting.rst

@@ -0,0 +1,51 @@
+.. _west-troubleshooting:
+
+Troubleshooting West
+####################
+
+This page covers common issues with west and how to solve them.
+
+"invalid choice: 'post-init'"
+*****************************
+
+If you see this error when running ``west init``:
+
+.. code-block:: none
+
+   west: error: argument <command>: invalid choice: 'post-init'
+   (choose from 'init', 'update', 'list', 'manifest', 'diff',
+   'status', 'forall', 'config', 'selfupdate', 'help')
+
+Then you have an old version of west installed, and are trying to use it in an
+installation that requires a more recent version.
+
+The easiest way to resolve this issue is to upgrade west and retry as follows:
+
+#. Install the latest west with the ``-U`` option for ``pip3 install`` as shown
+   in :ref:`west-install`.
+
+#. Back up any contents of :file:`zephyrproject/.west/config` that you want to
+   save. (If you don't have any configuration options set, it's safe to skip
+   this step.)
+
+#. Completely remove the :file:`zephyrproject/.west` directory (if you don't,
+   you will get the "already in an installation" error message discussed next).
+
+#. Run ``west init`` again.
+
+"already in an installation"
+****************************
+
+You may see this error when running ``west init``:
+
+.. code-block:: none
+
+   FATAL ERROR: already in an installation (<some directory>), aborting
+
+If this is unexpected and you're really trying to create a new installation,
+then it's likely that west is using the :envvar:`ZEPHYR_BASE` :ref:`environment
+variable <env_vars>` to locate a west installation elsewhere on your system.
+This is intentional behavior; it allows you to put your Zephyr applications in
+any directory and still use west.
+
+To resolve this issue, unset :envvar:`ZEPHYR_BASE` and try again.