Found solution for "pip/scons error: option –single-version-externally-managed not recognized" // Resolve #279

docs/faq.rst

@@ -75,6 +75,27 @@ There are a few options:
 - masking under Continuous Integration system via environment variable
   :envvar:`CI=true <CI>`.
 
+PlatformIO and ``scons`` aren't installed properly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Try these solutions:
+
+1. Upgrade SCons via `pip <https://pip.pypa.io>`_
+
+.. code-block:: bash
+
+    [sudo] pip uninstall scons
+    [sudo] pip install scons
+
+2. Install PlatformIO using :ref:`installation_installer_script`.
+
+.. _faq_troubleshooting_sconssingverextmanaged:
+
+PIP & SCons Error: option --single-version-externally-managed not recognized
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Answered in `issue #279 <https://github.com/platformio/platformio/issues/279>`_.
+
 .. _faq_troubleshooting_pionotfoundinpath:
 
 Program ``platformio`` not found in PATH
@@ -100,8 +121,8 @@ should contain ``/usr/local/bin`` directory.
 programs to the ``bin`` directory which is included in ``$PATH``. For example,
 see `issue #272 <https://github.com/platformio/platformio/issues/272#issuecomment-133626112>`_.
 
-Windows: ``UnicodeDecodeError: 'ascii' codec can't decode byte``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Windows UnicodeDecodeError: 'ascii' codec can't decode byte
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Answered in `issue #143 <https://github.com/platformio/platformio/issues/143#issuecomment-88060906>`_.
 
@@ -118,20 +139,20 @@ Please upgrade *SetupTools* package:
 
 .. code-block:: bash
 
-    $ [sudo] pip uninstall setuptools
-    $ [sudo] pip install setuptools
+    [sudo] pip uninstall setuptools
+    [sudo] pip install setuptools
 
     # Then re-install PlatformIO
-    $ [sudo] pip uninstall platformio
-    $ [sudo] pip install platformio
+    [sudo] pip uninstall platformio
+    [sudo] pip install platformio
 
-Windows: ``AttributeError: 'module' object has no attribute 'packages'``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Windows AttributeError: 'module' object has no attribute 'packages'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Answered in `issue #252 <https://github.com/platformio/platformio/issues/252#issuecomment-127072039>`_.
 
-ARM toolchain: ``cc1plus: error while loading shared libraries``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ARM toolchain: cc1plus: error while loading shared libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 See related answers for
 `error while loading shared libraries <https://github.com/platformio/platformio/issues?utf8=✓&q=error+while+loading+shared+libraries>`_.

docs/installation.rst

@@ -47,11 +47,14 @@ The latest stable version of PlatformIO may be done via
 .. code-block:: bash
 
     # update dependent packages to the latest versions
-    pip install -U pip setuptools virtualenv
+    pip install -U pip setuptools
 
-    # install the latest version of PlatformIO
+    # install/upgrade the latest version of PlatformIO
     pip install -U platformio
 
+.. warning::
+    Known Issue: :ref:`faq_troubleshooting_sconssingverextmanaged`
+
 Note that you may run into permissions issues running these commands. You have
 a few options here:
 
@@ -61,6 +64,8 @@ a few options here:
 * Run the command in a `virtualenv <https://virtualenv.pypa.io>`_ local to a
   specific project working set.
 
+.. _installation_installer_script:
+
 Installer Script
 ~~~~~~~~~~~~~~~~
 
@@ -134,9 +139,6 @@ For upgrading ``platformio`` to the latest version:
 Development Version
 ~~~~~~~~~~~~~~~~~~~
 
-.. warning::
-    We don't recommend to use ``develop`` version in production.
-
 Install the latest PlatformIO from the ``develop`` branch:
 
 .. code-block:: bash
@@ -163,4 +165,5 @@ Troubleshooting
     **Windows OS**: Please check that you have correctly installed USB driver
     from board manufacturer
 
-For further details, frequently questions, please refer to :ref:`faq`.
+For further details, frequently questions, known issues, please
+refer to :ref:`faq`.