[lldb][docs] Convert simple RST pages to Markdown (NFC) (#201256)

Convert nine short, low-risk RST docs to MyST Markdown as the first
batch of an incremental RST -> Markdown migration. Subsequent batches
will cover the rest.

Verified by building the docs on origin/main and on this branch with
identical sphinx flags and diffing the rendered HTML. Seven of nine
pages are byte-identical.

contributing.html differs in 42 lines, all attributable to `{doc}` xrefs
replacing RST hyperlinks to sibling pages (`reference external` ->
`reference internal`) and CommonMark collapsing two-spaces-after- period
to one.

ondemand.html differs in 26 lines because two bulleted lists that
followed a paragraph with no blank-line separator originally rendered as
literal `- ...` text in both RST and Markdown. The conversion tool
preserved that by emitting `\-`; this patch instead inserts a blank line
so they render as proper `<ul>` lists, fixing a latent doc bug.

Context:
https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/

Assisted-by: Claude

Author: JDevlieghere

lldb/docs/python_api.md

@@ -0,0 +1,15 @@
+# LLDB Python API
+
+% The long list of "skip" filters out several global functions that are
+% generated by SWIG (but which are not useful as they are only the
+% backend for their respective static functions in the classes).
+
+```{eval-rst}
+.. automodapi:: lldb
+  :no-inheritance-diagram:
+  :skip: command
+  :skip: declaration
+  :skip: in_range
+  :skip: is_numeric_type
+  :skip: lldb_iter
+```

lldb/docs/python_api.rst

@@ -1,47 +1,50 @@
-Python Extensions
-=================
+# Python Extensions
 
 LLDB provides scriptable extensions to augment the debugger's capabilities.
 This gives users the ability to tailor their debugging experience to their own needs.
 
 This page describes some of these scripting extensions:
 
-Operating System Thread Plugins
--------------------------------
+## Operating System Thread Plugins
 
+```{eval-rst}
 .. automodapi:: lldb.plugins.operating_system
     :no-heading:
     :skip: ScriptedThread
     :no-inheritance-diagram:
+```
 
-Scripted Frame Provider Plugins
--------------------------------
+## Scripted Frame Provider Plugins
 
+```{eval-rst}
 .. automodapi:: lldb.plugins.scripted_frame_provider
     :no-heading:
     :skip: ABCMeta
     :no-inheritance-diagram:
+```
 
-Scripted Process Plugins
--------------------------------
+## Scripted Process Plugins
 
+```{eval-rst}
 .. automodapi:: lldb.plugins.scripted_process
     :no-heading:
     :skip: ABCMeta
     :no-inheritance-diagram:
+```
 
-Scripted Platform Plugins
--------------------------------
+## Scripted Platform Plugins
 
+```{eval-rst}
 .. automodapi:: lldb.plugins.scripted_platform
     :no-heading:
     :skip: ABCMeta
     :no-inheritance-diagram:
+```
 
-Scripted Thread Plan Plugins
--------------------------------
+## Scripted Thread Plan Plugins
 
+```{eval-rst}
 .. automodapi:: lldb.plugins.scripted_thread_plan
     :no-heading:
     :no-inheritance-diagram:
-
+```

lldb/docs/python_extensions.rst lldb/docs/python_extensions.mdlldb/docs/python_extensions.rst renamed to lldb/docs/python_extensions.md

@@ -0,0 +1,63 @@
+# Caveats
+
+(python_caveat)=
+
+## Python
+
+LLDB has a powerful scripting interface which is accessible through Python.
+Python is available either from within 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 an 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.
+
+### LLDB in Xcode on macOS
+
+Users of lldb in Xcode on macOS commonly run into these issues when they
+install Python, often unknowingly as a dependency pulled in by Homebrew or
+other package managers. The problem is the symlinks that get created in
+`/usr/local/bin`, which comes before `/usr/bin` in your path. You can use
+`which python3` to check to what it resolves.
+
+To be sure you use the Python that matches with the lldb in Xcode use `xcrun`
+or use the absolute path to the shims in `/usr/bin`.
+
+```
+$ xcrun python3
+$ /usr/bin/python3
+```
+
+Similarly, to install packages and be able to use them from within lldb, you'll
+need to install them with the matching `pip3`.
+
+```
+$ xcrun pip3
+$ /usr/bin/pip3
+```
+
+The same is true for Python 2. Although Python 2 comes with the operating
+system rather than Xcode, you can still use `xcrun` to launch the system
+variant.
+
+```
+$ xcrun python
+$ /usr/bin/python
+```
+
+Keep in mind that Python 2 is deprecated and no longer maintained. Future
+versions of macOS will not include Python 2.7.