[Docs] Add Python caveats under the development section

[JDevlieghere]

Summary

This adds a page named Caveats with a section on some of the things to be aware of related to Python. It's a question we've seen more than once pop up and I think it's good to have it documentation on the website. Even though some of it might be useful to users, I still put it under "development" because it requires some understanding of how LLDB is built.

[aadsm]

Thank you for writing this up! I was thinking how I would find this.. I don't see myself clicking on the "Caveats" link (could also be a me problem though). Could we also add a link to it in this section? https://lldb.llvm.org/resources/build.html#id22. Something like "NOTE: You need to use the python binary you built with, check caveats to learn more"?

[aprantl]

lldb/docs/resources/caveats.rst

35

That 's confusingly worded... is the Python that's part of Xcode the same as the system's Python interpreter?

[JDevlieghere]

Address feedback

lldb/docs/index.rst

.. toctree::
    :maxdepth: 1
    :caption: Development
 
    resources/contributing
    resources/build
    resources/test
    resources/bots
    resources/sbapi
+   resources/caveats
 
 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: API Documentation
 
    Public Python API Reference <https://lldb.llvm.org/python_reference/index.html>
    Public C++ API Reference <https://lldb.llvm.org/cpp_reference/namespacelldb.html>

lldb/docs/resources/build.rst

 If you used a different build directory or made a release build, you may need
 to adjust the above to suit your needs. To test that the lldb Python module is
 built correctly and is available to the default Python interpreter, run:
 
 ::
 
   > python -c 'import lldb'
 
+
+Make sure you're using the Python interpreter that matches the Python library
+you linked against. For more details please refer to the :ref:`caveats
+<python_caveat>`.
+
 .. _CodeSigning:
 
 Code Signing on macOS
 ---------------------
 
 To use the in-tree debug server on macOS, lldb needs to be code signed. The
 Debug, DebugClang and Release builds are set to code sign using a code signing
 certificate named ``lldb_codesign``. This document explains how to set up the

lldb/docs/resources/caveats.rst

+Caveats
+=======
+
+.. contents::
+   :local:
+
+.. _python_caveat:
+
+Python
+------
+
+LLDB has a powerful scripting interface which is accessible through Python.
+Python is available either from withing LLDB through a (interactive) script
+interpreter, or as a Python module which you can import from the Python
+interpreter.
+
+To make this possible, LLDB links against the Python shared library. Linking
+against Python comes with some constraints to be aware of.
+
+1.  It is not possible to build and link LLDB against a Python 3 library and
+    use it from Python 2 and vice versa.
+
+2.  It is not possible to build and link LLDB against one distribution on
+    Python and use it through a interpreter coming from another distribution.
+    For example, on macOS, if you build and link against Python from
+    python.org, you cannot import the lldb module from the Python interpreter
+    installed with Homebrew.
+
+3.  To use third party Python packages from inside LLDB, you need to install
+    them using a utility (such as ``pip``) from the same Python distribution as
+    the one used to build and link LLDB.
+
+The previous considerations are especially important during development, but
+apply to binary distributions of LLDB as well. For example, the LLDB that comes
+with Xcode links against the Python 3 that's part of Xcode. Therefore you
+should always use the Python in Xcode (through ``xcrun python3`` or
+``/usr/bin/python3``) to import the lldb module or install packages.