[lldb/docs] Add scripting extensions documentation to the website (llvm#97262)

This patch adds the documentation for a subset of scripting extensions
such as scripted process, scripted thread, operating system threads &
scritped thread plans to the lldb website.

Signed-off-by: Med Ismail Bennani <[email protected]>

Author: medismailben

lldb/docs/CMakeLists.txt

@@ -27,8 +27,13 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
     get_target_property(lldb_bindings_dir swig_wrapper_python BINARY_DIR)
     add_custom_target(lldb-python-doc-package
       COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_bindings_dir}/lldb.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
+      COMMAND "${CMAKE_COMMAND}" -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins"
+      COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_process.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+      COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+      COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
       COMMENT "Copying lldb.py to pretend its a Python package.")
-    add_dependencies(lldb-python-doc-package swig_wrapper_python)
+
+    add_dependencies(lldb-python-doc-package swig_wrapper_python lldb-python)
 
     # FIXME: Don't treat Sphinx warnings as errors. The files generated by
     # automodapi are full of warnings (partly caused by SWIG, our documentation

lldb/docs/index.rst

@@ -141,6 +141,7 @@ interesting areas to contribute to lldb.
    use/python
    use/python-reference
    Python API <python_api>
+   Python Extensions <python_extensions>
 
 
 .. toctree::

lldb/examples/python/templates/operating_system.py

@@ -10,16 +10,16 @@ class OperatingSystem(ScriptedThread):
     """
     Class that provides data for an instance of a LLDB 'OperatingSystemPython' plug-in class.
 
-    ```
-    thread_info = {
-        "tid": tid,
-        "name": "four",
-        "queue": "queue4",
-        "state": "stopped",
-        "stop_reason": "none",
-        "core" : 2
-    }
-    ```
+    .. code-block:: python
+
+        thread_info = {
+            "tid": tid,
+            "name": "four",
+            "queue": "queue4",
+            "state": "stopped",
+            "stop_reason": "none",
+            "core" : 2
+        }
 
     - tid : thread ID (mandatory)
     - name : thread name (optional key/value pair)

lldb/examples/python/templates/scripted_platform.py

@@ -10,9 +10,6 @@ class ScriptedPlatform(metaclass=ABCMeta):
 
     Most of the base class methods are `@abstractmethod` that need to be
     overwritten by the inheriting class.
-
-    DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
-                THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
     """
 
     processes = None
@@ -32,16 +29,18 @@ def __init__(self, exe_ctx, args):
     def list_processes(self):
         """Get a list of processes that are running or that can be attached to on the platform.
 
-        processes = {
-            420: {
-                    name: a.out,
-                    arch: aarch64,
-                    pid: 420,
-                    parent_pid: 42 (optional),
-                    uid: 0 (optional),
-                    gid: 0 (optional),
-            },
-        }
+        .. code-block:: python
+
+            processes = {
+                420: {
+                        name: a.out,
+                        arch: aarch64,
+                        pid: 420,
+                        parent_pid: 42 (optional),
+                        uid: 0 (optional),
+                        gid: 0 (optional),
+                },
+            }
 
         Returns:
             Dict: The processes represented as a dictionary, with at least the

lldb/examples/python/templates/scripted_process.py

@@ -11,9 +11,6 @@ class ScriptedProcess(metaclass=ABCMeta):
 
     Most of the base class methods are `@abstractmethod` that need to be
     overwritten by the inheriting class.
-
-    DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
-                THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
     """
 
     capabilities = None
@@ -106,8 +103,8 @@ def write_memory_at_address(self, addr, data, error):
 
         Args:
             addr (int): Address from which we should start reading.
-            data (lldb.SBData): An `lldb.SBData` buffer to write to the
-                process memory.
+            data (lldb.SBData): An `lldb.SBData` buffer to write to the process
+            memory.
             error (lldb.SBError): Error object.
 
         Returns:
@@ -121,13 +118,13 @@ def write_memory_at_address(self, addr, data, error):
     def get_loaded_images(self):
         """Get the list of loaded images for the scripted process.
 
-        ```
-        scripted_image = {
-            uuid = "c6ea2b64-f77c-3d27-9528-74f507b9078b",
-            path = "/usr/lib/dyld"
-            load_addr = 0xbadc0ffee
-        }
-        ```
+        .. code-block:: python
+
+            scripted_image = {
+                uuid = "c6ea2b64-f77c-3d27-9528-74f507b9078b",
+                path = "/usr/lib/dyld"
+                load_addr = 0xbadc0ffee
+            }
 
         Returns:
             List[scripted_image]: A list of `scripted_image` dictionaries
@@ -238,9 +235,6 @@ class ScriptedThread(metaclass=ABCMeta):
 
     Most of the base class methods are `@abstractmethod` that need to be
     overwritten by the inheriting class.
-
-    DISCLAIMER: THIS INTERFACE IS STILL UNDER DEVELOPMENT AND NOT STABLE.
-                THE METHODS EXPOSED MIGHT CHANGE IN THE FUTURE.
     """
 
     @abstractmethod
@@ -305,10 +299,12 @@ def get_name(self):
     def get_state(self):
         """Get the scripted thread state type.
 
+        .. code-block:: python
+
             eStateStopped,   ///< Process or thread is stopped and can be examined.
             eStateRunning,   ///< Process or thread is running and can't be examined.
-            eStateStepping,  ///< Process or thread is in the process of stepping and can
-                             /// not be examined.
+            eStateStepping,  ///< Process or thread is in the process of stepping and
+                             /// can not be examined.
             eStateCrashed,   ///< Process or thread has crashed and can be examined.
 
         Returns:
@@ -340,12 +336,12 @@ def get_stop_reason(self):
     def get_stackframes(self):
         """Get the list of stack frames for the scripted thread.
 
-        ```
-        scripted_frame = {
-            idx = 0,
-            pc = 0xbadc0ffee
-        }
-        ```
+        .. code-block:: python
+
+            scripted_frame = {
+                idx = 0,
+                pc = 0xbadc0ffee
+            }
 
         Returns:
             List[scripted_frame]: A list of `scripted_frame` dictionaries