Create "common issues" page and include BrickPi info

CONTRIBUTING.rst

@@ -6,10 +6,10 @@ This repository holds the Python bindings for ev3dev_, ev3dev-lang-python.
 Opening issues
 --------------
 
-Please make sure you have read the FAQ_. If you are still encountering your
-problem, open an issue, and ensure that the questions asked by the issue
-template are completely answered with correct info. This will make it much
-easier for us to help you!
+Please make sure you have read the FAQ_ and `Common Issues`_. If you are still
+encountering your problem, open an issue, and ensure that the questions asked
+by the issue template are completely answered with correct info. This will make
+it much easier for us to help you!
 
 Submitting Pull Requests
 ------------------------
@@ -105,3 +105,4 @@ following commands:
 
 .. _ev3dev: http://ev3dev.org
 .. _FAQ: https://python-ev3dev.readthedocs.io/en/ev3dev-stretch/faq.html
+.. _Common Issues: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html

README.rst

@@ -70,7 +70,7 @@ If you encounter an error such as
 ``/usr/bin/env: 'python3\r': No such file or directory``,
 you must switch your editor's "line endings" setting for the file from
 "CRLF" to just "LF". This is usually in the status bar at the bottom.
-For help, see `our FAQ page`_.
+For help, see our `Common Issues page`_.
 
 Important: Make your script executable (non-Visual Studio Code only)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -202,7 +202,8 @@ Frequently-Asked Questions
 --------------------------
 
 Experiencing an odd error or unsure of how to do something that seems
-simple? Check our our `FAQ`_ to see if there's an existing answer.
+simple? Check our our `FAQ`_ and `Common Issues page`_ to see if there's an
+existing answer.
 
 
 .. _ev3dev: http://ev3dev.org
@@ -218,6 +219,7 @@ simple? Check our our `FAQ`_ to see if there's an existing answer.
 .. _ev3python.com: http://ev3python.com/
 .. _FAQ: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/faq.html
 .. _our FAQ page: FAQ_
+.. _Common Issues page: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
 .. _our Issues tracker: https://github.com/ev3dev/ev3dev-lang-python/issues
 .. _EXPLOR3R: demo-robot_
 .. _demo-robot: http://robotsquare.com/2015/10/06/explor3r-building-instructions/

docs/common-issues.rst

@@ -0,0 +1,55 @@
+Common Issues with ev3dev-lang-python
+=====================================
+
+``ImportError: No module named ev3dev2``
+----------------------------------------
+
+This likely means you are running the script on your computer rather than on the
+EV3 (or other ev3dev platform). You can run it using our
+`Visual Studio Code extension`_ by connecting to a device from the "Explore" tab
+on the left and then going to the debug tab, selecting "Run and Debug", and
+choosing the ev3dev option.
+
+.. image:: _static/vscode-debug.png
+
+``/usr/bin/env: 'python3\r': No such file or directory``
+--------------------------------------------------------
+
+This means your file includes Windows-style line endings
+(CRLF--carriage-return line-feed), which are often inserted by editors on
+Windows. To resolve this issue, open an SSH session and run the following
+command, replacing ``<file>`` with the name of the Python file you're
+using:
+
+.. code:: shell
+
+    sed -i 's/\r//g' <file>
+
+This will fix it for the copy of the file on the brick, but if you plan to edit
+it again from Windows, you should configure your editor to use Unix-style
+line endings (LF/line-feed). In Visual Studio Code, there is an option in the
+lower-right corner.
+
+.. image:: _static/vscode-crlf.png
+
+For PyCharm, you can find a guide on doing this
+`here <https://www.jetbrains.com/help/pycharm/2016.2/configuring-line-separators.html>`_.
+Most other editors have similar options; there may be an option for it in the
+status bar at the bottom of the window or in the menu bar at the top.
+
+
+``Exception: Unsupported platform 'None'``
+------------------------------------------
+
+If you are on a Raspberry Pi, you probably forgot to `update config.txt`_.
+
+
+Using BrickPi 3: sensors aren't found
+-------------------------------------
+
+The BrickPi can't automatically detect what sensors are plugged in, so you need
+to tell it. See the `BrickPi 3 demo`_.
+
+.. _update config.txt: https://www.ev3dev.org/docs/getting-started/#step-3a-raspberry-pi-only-update-options-in-configtxt
+.. _Visual Studio Code extension: https://github.com/ev3dev/vscode-ev3dev-browser
+.. _BrickPi 3 demo: https://github.com/ev3dev/ev3dev-lang-python-demo/blob/stretch/platform/brickpi3-motor-and-sensor.py

docs/faq.rst

@@ -1,23 +1,7 @@
 Frequently-Asked Questions
 ==========================
 
-Q: Why does my Python program exit quickly or immediately throw an error?
-    A: This may occur if your file includes Windows-style line endings
-    (CRLF--carriage-return line-feed), which are often inserted by editors on
-    Windows. To resolve this issue, open an SSH session and run the following
-    command, replacing ``<file>`` with the name of the Python file you're
-    using:
-
-    .. code:: shell
-
-        sed -i 's/\r//g' <file>
-
-    This will fix it for the copy of the file on the brick, but if you plan to edit
-    it again from Windows, you should configure your editor to use Unix-style
-    line endings (LF--line-feed). For PyCharm, you can find a guide on doing this
-    `here <https://www.jetbrains.com/help/pycharm/2016.2/configuring-line-separators.html>`_.
-    Most other editors have similar options; there may be an option for it in the
-    status bar at the bottom of the window or in the menu bar at the top.
+See also `Common Issues`_.
 
 Q: Where can I learn more about the ev3dev operating system?
     A: `ev3dev.org`_ is a great resource for finding guides and tutorials on
@@ -63,6 +47,7 @@ Q: What compatibility issues are there with the different versions of Python?
 .. _ev3python.com: http://ev3python.com/
 .. _FAQ: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/faq.html
 .. _our FAQ page: FAQ_
+.. _Common Issues: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
 .. _our Issues tracker: https://github.com/ev3dev/ev3dev-lang-python/issues
 .. _EXPLOR3R: demo-robot_
 .. _demo-robot: http://robotsquare.com/2015/10/06/explor3r-building-instructions/

docs/index.rst

@@ -10,3 +10,4 @@
    spec
    rpyc
    faq
+   common-issues

docs/sensors.rst

@@ -6,7 +6,9 @@ Sensor classes
 *Note:* If you are using a BrickPi rather than an EV3, you will need to manually
 configure the ports before interacting with your sensors. See the example
 `here <https://github.com/ev3dev/ev3dev-lang-python-demo/blob/stretch/platform/brickpi3-motor-and-sensor.py>`_.
+There are other common issues specific to the BrickPi; check out `Common Issues`_.
 
+.. _Common Issues: http://python-ev3dev.readthedocs.io/en/ev3dev-stretch/common-issues.html
 
 Dedicated sensor classes
 ------------------------