Merge pull request #27 from freakboy3742/install-errors

Fixes #25 -- Detail how to deal with install failures.

docs/tutorial/tutorial-0.rst

@@ -30,6 +30,8 @@ Debian/Ubuntu/Mint; ``dnf`` on Fedora, or ``pacman`` on Arch).
     can run `python3` from your operating system's command prompt/terminal
     application, and get a working Python interpreter.
 
+.. _install-dependencies:
+
 Install dependencies
 ====================
 
@@ -66,7 +68,6 @@ Next, install the additional dependencies needed for your operating system:
 
     .. code-block:: bash
 
-      # Fedora
       $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-devel cairo-gobject-devel pango-devel webkitgtk3
 
   .. group-tab:: Windows

docs/tutorial/tutorial-1.rst

@@ -27,14 +27,75 @@ the ``beeware-venv`` virtual environment activated, and run:
 
       (beeware-venv) $ pip install --pre beeware
 
+    .. admonition:: Possible errors during installation
+
+        If you see errors during installation, it's almost certainly because
+        some of the system requirements haven't been installed. Make sure you
+        have :ref:`installed all the platform pre-requisistes
+        <install-dependencies>`.
+
   .. group-tab:: Windows
 
     .. code-block:: doscon
 
       (beeware-venv)C:\...>pip install --pre beeware
 
-
-ℹ️ : ``--pre`` is a flag to tell ``pip`` to install pre-release or development versions. This ensures you are installing the most recent development version of Beeware. 
+    .. admonition:: Possible errors during installation
+
+        On some versions of Python, installing the ``beeware`` package will
+        raise an error. This will usually manifest as:
+
+        .. code-block:: doscon
+
+                Traceback (most recent call last):
+                  File "<string>", line 1, in <module>
+                  File "C:\...\Local\Temp\pip-install-ytuu_37_\pythonnet\setup.py", line 18, in <module>
+                    from wheel import bdist_wheel
+                ModuleNotFoundError: No module named 'wheel'
+                ----------------------------------------
+            ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
+
+        Depending on the specifics of your environment, it might also manifest
+        as a report that includes the following:
+
+        .. code-block:: doscon
+
+              Building wheel for pythonnet (setup.py) ... error
+              ERROR: Command errored out with exit status 1:
+              ...
+                File "c:\...\Local\Programs\Python\Python38\lib\subprocess.py", line 364, in check_call
+                  raise CalledProcessError(retcode, cmd)
+              subprocess.CalledProcessError: Command '['...\\python.exe', 'tools\\geninterop\\geninterop.py', 'src\\runtime\\interop38.cs']' returned non-zero exit status 1.
+              ----------------------------------------
+              ERROR: Failed building wheel for pythonnet
+              Running setup.py clean for pythonnet
+            Failed to build pythonnet
+
+        This is caused because the ``beeware`` package has dependencies, and on
+        Windows, one of those dependencies is `Python for .NET
+        <http://pythonnet.github.io/>`__. Python for .NET isn't a pure Python
+        package - it contains C# modules that need to be compiled. The Python
+        for .NET team publishes pre-compiled versions of these modules, but
+        they sometimes lag behind in support of more recent versions of Python.
+
+        If you get this error, you have three options:
+
+         1. Use an older version of Python. Check the `pythonnet entry on
+            PyPI <https://pypi.org/project/pythonnet/>`__ to see the versions
+            of Python currently supported by Python for .NET.
+
+         2. Configure your environment to support compiling Python for .NET.
+            This is a moderately complex process, and will require you to have
+            Visual Studio. See `the Python for .NET wiki
+            <https://github.com/pythonnet/pythonnet/wiki/Installation>`__ for
+            details.
+
+         3. Install an unofficial compiled wheel. The Python for .NET team
+            suggests `this collection of wheels
+            <https://www.lfd.uci.edu/~gohlke/pythonlibs/#pythonnet>`__ as a
+            possible source. The `.whl` file can be installed with
+            ``pip install somefile.whl``; you should then be able to re-run
+            ``pip install --pre beeware``.
 
 One of the BeeWare tools is **Briefcase**. Briefcase can be used to package
 your application for distribution to end users - but it can also be used to