[Lldb-commits] [lldb] [lldb][docs] Convert top-level RST docs to Markdown (NFC) (PR #201674)
via lldb-commits
lldb-commits at lists.llvm.org
Thu Jun 4 12:47:18 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: Jonas Devlieghere (JDevlieghere)
<details>
<summary>Changes</summary>
Convert the two remaining top-level RST docs, index and python_api_enums, to MyST Markdown. This is the final batch of an incremental RST -> Markdown migration.
After this change, the only RST sources left under lldb/docs/ are man/lldb.rst and man/lldb-server.rst, which conf.py intentionally keeps as RST so the man-page builder can run without myst_parser installed (this reduces dependencies for some llvm distributions).
Verified by building the docs on origin/main and on this branch with identical sphinx flags and diffing both the warnings and the rendered HTML. After file extension and line numbers are normalized, the warning sets match exactly. index.html is byte-identical; python_api_enums.html differs in a single line where CommonMark collapses two spaces after a period to one.
The diff also surfaced two semantic regressions in the conversion, fixed here:
- index.md and python_api_enums.md lost cross-reference behavior on single-backtick refs to `lldb` and `SBHostOS.GetLLDBPath`. RST's default role is `any`, so single backticks attempted xrefs; in MyST single backticks are plain code spans. Converted to explicit `{any}`...`` syntax.
Context:
https://discourse.llvm.org/t/rfc-make-myst-markdown-the-llvm-docs-format-rip-rest/
Assisted-by: Claude
---
Patch is 68.50 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/201674.diff
3 Files Affected:
- (added) lldb/docs/index.md (+225)
- (removed) lldb/docs/index.rst (-223)
- (renamed) lldb/docs/python_api_enums.md (+2051-197)
``````````diff
diff --git a/lldb/docs/index.md b/lldb/docs/index.md
new file mode 100644
index 0000000000000..da015b5d2e1ce
--- /dev/null
+++ b/lldb/docs/index.md
@@ -0,0 +1,225 @@
+```{title} LLDB Homepage
+```
+
+# The LLDB Debugger
+
+Welcome to the LLDB documentation!
+
+LLDB is a next generation, high-performance debugger. It is built as a set of
+reusable components which highly leverage existing libraries in the larger
+[LLVM Project](https://llvm.org), such as the Clang expression parser and
+LLVM disassembler.
+
+LLDB is the default debugger in Xcode on macOS and supports debugging C,
+Objective-C and C++ on the desktop and iOS devices and simulator.
+
+All of the code in the LLDB project is available under the
+["Apache 2.0 License with LLVM exceptions"][apache-2-0-license-with-llvm-exceptions].
+
+[apache-2-0-license-with-llvm-exceptions]: https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework
+
+## Using LLDB
+
+For an introduction into the LLDB command language, head over to the [LLDB
+Tutorial](https://lldb.llvm.org/use/tutorial.html). For users already familiar
+with GDB there is a cheat sheet listing common tasks and their LLDB equivalent
+in the [GDB to LLDB command map](https://lldb.llvm.org/use/map.html).
+
+There are also multiple resources on how to script LLDB using Python: the
+{doc}`use/python-reference` is a great starting point for that.
+
+## Compiler Integration Benefits
+
+LLDB converts debug information into Clang types so that it can
+leverage the Clang compiler infrastructure. This allows LLDB to support the
+latest C, C++, Objective-C and Objective-C++ language features and runtimes in
+expressions without having to reimplement any of this functionality. It also
+leverages the compiler to take care of all ABI details when making functions
+calls for expressions, when disassembling instructions and extracting
+instruction details, and much more.
+
+The major benefits include:
+
+- Up to date language support for C, C++, Objective-C
+- Multi-line expressions that can declare local variables and types
+- Utilize the JIT for expressions when supported
+- Evaluate expression Intermediate Representation (IR) when JIT can't be used
+
+## Reusability
+
+The LLDB debugger APIs are exposed as a C++ object oriented interface in a
+shared library. The lldb command line tool links to, and uses this public API.
+On macOS the shared library is exposed as a framework named LLDB.framework,
+and Unix systems expose it as lldb.so. The entire API is also then exposed
+through Python script bindings which allow the API to be used within the LLDB
+embedded script interpreter, and also in any python script that loads the
+lldb.py module in standard python script files. See the Python Reference page
+for more details on how and where Python can be used with the LLDB API.
+
+Sharing the LLDB API allows LLDB to not only be used for debugging, but also
+for symbolication, disassembly, object and symbol file introspection, and much
+more.
+
+## Platform Support
+
+LLDB is known to work on the following platforms, but ports to new platforms
+are welcome:
+
+- macOS debugging for i386, x86_64 and AArch64
+- iOS, tvOS, and watchOS simulator debugging on i386, x86_64 and AArch64
+- iOS, tvOS, and watchOS device debugging on ARM and AArch64
+- Linux user-space debugging for i386, x86_64, ARM, AArch64, PPC64le, s390x
+- FreeBSD user-space debugging for i386, x86_64, ARM, AArch64, PPC
+- FreeBSD kernel debugging for i386, x86_64, ARM, AArch64, PPC64le, RISCV64
+- NetBSD user-space debugging for i386 and x86_64
+- Windows user-space debugging for i386, x86_64, ARM and AArch64 (\*)
+
+(\*) Support for Windows is under active development. Basic functionality is
+expected to work, with functionality improving rapidly. ARM and AArch64 support
+is more experimental, with more known issues than the others.
+
+Support for the following architectures is in active development. For their
+current state, follow the links to their respective issues:
+
+- [RISC-V](https://github.com/llvm/llvm-project/issues/55383)
+- [LoongArch](https://github.com/llvm/llvm-project/issues/112693)
+- [WebAssembly](https://github.com/llvm/llvm-project/issues/150449)
+
+## Get Involved
+
+Check out the LLVM source-tree with git and find the sources in the {any}`lldb`
+subdirectory:
+
+```
+$ git clone https://github.com/llvm/llvm-project.git
+```
+
+Note that LLDB generally builds from top-of-trunk using CMake and Ninja.
+Additionally it builds:
+
+- on macOS with a {ref}`generated Xcode project <CMakeGeneratedXcodeProject>`
+- on Linux and FreeBSD with Clang and libstdc++/libc++
+- on NetBSD with GCC/Clang and libstdc++/libc++
+- on Windows with a generated project for VS 2017 or higher
+
+See the {doc}`LLDB Build Page <resources/build>` for build instructions.
+
+Discussions about LLDB should go to the [LLDB forum](https://discourse.llvm.org/c/subprojects/lldb) or the `lldb` channel on
+the [LLVM Discord server](https://discord.com/invite/xS7Z362).
+
+For contributions follow the
+[LLVM contribution process](https://llvm.org/docs/Contributing.html). Commit
+messages are automatically sent to the [lldb-commits](http://lists.llvm.org/mailman/listinfo/lldb-commits) mailing list.
+
+See the {doc}`Projects page <resources/projects>` if you are looking for some
+interesting areas to contribute to lldb.
+
+```{toctree}
+:caption: Getting Started
+:hidden: true
+:maxdepth: 1
+
+use/tutorial
+use/map
+use/settings
+use/troubleshooting
+Man Page <man/lldb>
+```
+
+```{toctree}
+:caption: Using LLDB
+:hidden: true
+:maxdepth: 1
+
+use/variable
+use/formatting
+use/repeat-commands
+use/symbolication
+use/symbols
+use/ondemand
+use/remote
+```
+
+```{toctree}
+:caption: IDE & Tool Integration
+:hidden: true
+:maxdepth: 1
+
+use/lldbdap
+use/mcp
+```
+
+```{toctree}
+:caption: Platform-Specific Topics
+:hidden: true
+:maxdepth: 1
+
+use/aarch64-linux
+use/intel_pt
+```
+
+```{toctree}
+:caption: Scripting LLDB
+:hidden: true
+:maxdepth: 1
+
+use/python-reference
+Python API <python_api>
+Python Extensions <python_extensions>
+```
+
+```{toctree}
+:caption: Contributing to LLDB
+:hidden: true
+:maxdepth: 1
+
+resources/overview
+resources/contributing
+resources/lldbdap-contributing
+resources/build
+resources/test
+resources/qemu-testing
+resources/debugging
+resources/fuzzing
+```
+
+```{toctree}
+:caption: Architecture & Internals
+:hidden: true
+:maxdepth: 1
+
+Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
+Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
+resources/sbapi
+resources/dataformatters
+resources/formatterbytecode
+resources/addinglanguagesupport
+resources/caveats
+resources/projects
+```
+
+```{toctree}
+:caption: Protocol & Format Specifications
+:hidden: true
+:maxdepth: 1
+
+resources/lldbgdbremote
+resources/lldbplatformpackets
+resources/extensions
+use/symbolfilejson
+```
+
+```{toctree}
+:caption: Resources
+:hidden: true
+:maxdepth: 1
+
+use/links
+Source Code <https://github.com/llvm/llvm-project>
+Releases <https://github.com/llvm/llvm-project/releases>
+Discord Channel <https://discord.com/channels/636084430946959380/636732809708306432>
+Discussion Forums <https://discourse.llvm.org/c/subprojects/lldb/8>
+Developer Policy <https://llvm.org/docs/DeveloperPolicy.html>
+Bug Reports <https://github.com/llvm/llvm-project/issues?q=is%3Aissue+label%3Alldb+is%3Aopen>
+Code Reviews <https://github.com/llvm/llvm-project/pulls?q=is%3Apr+label%3Alldb+is%3Aopen>
+```
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
deleted file mode 100644
index d8886aeef26ec..0000000000000
--- a/lldb/docs/index.rst
+++ /dev/null
@@ -1,223 +0,0 @@
-.. title:: LLDB Homepage
-
-The LLDB Debugger
-=================
-
-Welcome to the LLDB documentation!
-
-LLDB is a next generation, high-performance debugger. It is built as a set of
-reusable components which highly leverage existing libraries in the larger
-`LLVM Project <https://llvm.org>`_, such as the Clang expression parser and
-LLVM disassembler.
-
-LLDB is the default debugger in Xcode on macOS and supports debugging C,
-Objective-C and C++ on the desktop and iOS devices and simulator.
-
-All of the code in the LLDB project is available under the
-`"Apache 2.0 License with LLVM exceptions"`_.
-
-.. _"Apache 2.0 License with LLVM exceptions": https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework
-
-Using LLDB
-----------
-
-For an introduction into the LLDB command language, head over to the `LLDB
-Tutorial <https://lldb.llvm.org/use/tutorial.html>`_. For users already familiar
-with GDB there is a cheat sheet listing common tasks and their LLDB equivalent
-in the `GDB to LLDB command map <https://lldb.llvm.org/use/map.html>`_.
-
-There are also multiple resources on how to script LLDB using Python: the
-:doc:`use/python-reference` is a great starting point for that.
-
-Compiler Integration Benefits
------------------------------
-
-LLDB converts debug information into Clang types so that it can
-leverage the Clang compiler infrastructure. This allows LLDB to support the
-latest C, C++, Objective-C and Objective-C++ language features and runtimes in
-expressions without having to reimplement any of this functionality. It also
-leverages the compiler to take care of all ABI details when making functions
-calls for expressions, when disassembling instructions and extracting
-instruction details, and much more.
-
-The major benefits include:
-
-- Up to date language support for C, C++, Objective-C
-- Multi-line expressions that can declare local variables and types
-- Utilize the JIT for expressions when supported
-- Evaluate expression Intermediate Representation (IR) when JIT can't be used
-
-Reusability
------------
-
-The LLDB debugger APIs are exposed as a C++ object oriented interface in a
-shared library. The lldb command line tool links to, and uses this public API.
-On macOS the shared library is exposed as a framework named LLDB.framework,
-and Unix systems expose it as lldb.so. The entire API is also then exposed
-through Python script bindings which allow the API to be used within the LLDB
-embedded script interpreter, and also in any python script that loads the
-lldb.py module in standard python script files. See the Python Reference page
-for more details on how and where Python can be used with the LLDB API.
-
-Sharing the LLDB API allows LLDB to not only be used for debugging, but also
-for symbolication, disassembly, object and symbol file introspection, and much
-more.
-
-Platform Support
-----------------
-
-LLDB is known to work on the following platforms, but ports to new platforms
-are welcome:
-
-* macOS debugging for i386, x86_64 and AArch64
-* iOS, tvOS, and watchOS simulator debugging on i386, x86_64 and AArch64
-* iOS, tvOS, and watchOS device debugging on ARM and AArch64
-* Linux user-space debugging for i386, x86_64, ARM, AArch64, PPC64le, s390x
-* FreeBSD user-space debugging for i386, x86_64, ARM, AArch64, PPC
-* FreeBSD kernel debugging for i386, x86_64, ARM, AArch64, PPC64le, RISCV64
-* NetBSD user-space debugging for i386 and x86_64
-* Windows user-space debugging for i386, x86_64, ARM and AArch64 (*)
-
-(*) Support for Windows is under active development. Basic functionality is
-expected to work, with functionality improving rapidly. ARM and AArch64 support
-is more experimental, with more known issues than the others.
-
-Support for the following architectures is in active development. For their
-current state, follow the links to their respective issues:
-
-* `RISC-V <https://github.com/llvm/llvm-project/issues/55383>`_
-* `LoongArch <https://github.com/llvm/llvm-project/issues/112693>`_
-* `WebAssembly <https://github.com/llvm/llvm-project/issues/150449>`_
-
-Get Involved
-------------
-
-Check out the LLVM source-tree with git and find the sources in the `lldb`
-subdirectory:
-
-::
-
- $ git clone https://github.com/llvm/llvm-project.git
-
-Note that LLDB generally builds from top-of-trunk using CMake and Ninja.
-Additionally it builds:
-
-* on macOS with a :ref:`generated Xcode project <CMakeGeneratedXcodeProject>`
-* on Linux and FreeBSD with Clang and libstdc++/libc++
-* on NetBSD with GCC/Clang and libstdc++/libc++
-* on Windows with a generated project for VS 2017 or higher
-
-See the :doc:`LLDB Build Page <resources/build>` for build instructions.
-
-Discussions about LLDB should go to the `LLDB forum
-<https://discourse.llvm.org/c/subprojects/lldb>`__ or the ``lldb`` channel on
-the `LLVM Discord server <https://discord.com/invite/xS7Z362>`__.
-
-For contributions follow the
-`LLVM contribution process <https://llvm.org/docs/Contributing.html>`__. Commit
-messages are automatically sent to the `lldb-commits
-<http://lists.llvm.org/mailman/listinfo/lldb-commits>`__ mailing list.
-
-See the :doc:`Projects page <resources/projects>` if you are looking for some
-interesting areas to contribute to lldb.
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Getting Started
-
- use/tutorial
- use/map
- use/settings
- use/troubleshooting
- Man Page <man/lldb>
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Using LLDB
-
- use/variable
- use/formatting
- use/repeat-commands
- use/symbolication
- use/symbols
- use/ondemand
- use/remote
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: IDE & Tool Integration
-
- use/lldbdap
- use/mcp
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Platform-Specific Topics
-
- use/aarch64-linux
- use/intel_pt
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Scripting LLDB
-
- use/python-reference
- Python API <python_api>
- Python Extensions <python_extensions>
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Contributing to LLDB
-
- resources/overview
- resources/contributing
- resources/lldbdap-contributing
- resources/build
- resources/test
- resources/qemu-testing
- resources/debugging
- resources/fuzzing
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Architecture & Internals
-
- Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
- Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
- resources/sbapi
- resources/dataformatters
- resources/formatterbytecode
- resources/addinglanguagesupport
- resources/caveats
- resources/projects
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Protocol & Format Specifications
-
- resources/lldbgdbremote
- resources/lldbplatformpackets
- resources/extensions
- use/symbolfilejson
-
-.. toctree::
- :hidden:
- :maxdepth: 1
- :caption: Resources
-
- use/links
- Source Code <https://github.com/llvm/llvm-project>
- Releases <https://github.com/llvm/llvm-project/releases>
- Discord Channel <https://discord.com/channels/636084430946959380/636732809708306432>
- Discussion Forums <https://discourse.llvm.org/c/subprojects/lldb/8>
- Developer Policy <https://llvm.org/docs/DeveloperPolicy.html>
- Bug Reports <https://github.com/llvm/llvm-project/issues?q=is%3Aissue+label%3Alldb+is%3Aopen>
- Code Reviews <https://github.com/llvm/llvm-project/pulls?q=is%3Apr+label%3Alldb+is%3Aopen>
diff --git a/lldb/docs/python_api_enums.rst b/lldb/docs/python_api_enums.md
similarity index 66%
rename from lldb/docs/python_api_enums.rst
rename to lldb/docs/python_api_enums.md
index a43a47b8d6985..206745e9e5a8c 100644
--- a/lldb/docs/python_api_enums.rst
+++ b/lldb/docs/python_api_enums.md
@@ -1,551 +1,1089 @@
-..
- This is a sub page of the Python API docs and linked from the main API page.
- The page isn't in any toctree, so silence the sphinx warnings by marking it as orphan.
+---
+orphan: true
+---
-:orphan:
+% This is a sub page of the Python API docs and linked from the main API page.
+% The page isn't in any toctree, so silence the sphinx warnings by marking it as orphan.
-Python API enumerators and constants
-====================================
+# Python API enumerators and constants
+```{eval-rst}
.. py:currentmodule:: lldb
+```
-Constants
-*********
+## Constants
-Generic register numbers
-------------------------
+### Generic register numbers
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_PC
Program counter.
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_SP
Stack pointer.
+```
+
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_FP
Frame pointer.
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_RA
Return address.
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_FLAGS
Processor flags register.
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG1
The register that would contain pointer size or less argument 1 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG2
The register that would contain pointer size or less argument 2 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG3
The register that would contain pointer size or less argument 3 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG4
The register that would contain pointer size or less argument 4 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG5
The register that would contain pointer size or less argument 5 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG6
The register that would contain pointer size or less argument 6 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG7
The register that would contain pointer size or less argument 7 (if any).
+```
+```{eval-rst}
.. py:data:: LLDB_REGNUM_GENERIC_ARG8
The register that would contain pointer size or less argument 8 (if any).
+```
-Invalid value definitions
--------------------------
+### Invalid value definitions
+```{eval-rst}
.. py:data:: LLDB_INVALID_BREAK_ID
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_WATCH_ID
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_ADDRESS
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_INDEX32
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_IVAR_OFFSET
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_IMAGE_TOKEN
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_MODULE_VERSION
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_REGNUM
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_UID
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_PROCESS_ID
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_THREAD_ID
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_FRAME_ID
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_SIGNAL_NUMBER
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_OFFSET
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_LINE_NUMBER
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_QUEUE_ID
+```
-CPU types
----------
+### CPU types
+```{eval-rst}
.. py:data:: LLDB_ARCH_DEFAULT
+```
+
+```{eval-rst}
.. py:data:: LLDB_ARCH_DEFAULT_32BIT
+```
+
+```{eval-rst}
.. py:data:: LLDB_ARCH_DEFAULT_64BIT
+```
+
+```{eval-rst}
.. py:data:: LLDB_INVALID_CPUTYPE
+```
-Option set definitions
-----------------------
+### Option set definitions
+```{eval-rst}
.. py:data:: LLDB_MAX_NUM_OPTION_SETS
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_ALL
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_1
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_2
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_3
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_4
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_5
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_6
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_7
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_8
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_9
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_10
+```
+
+```{eval-rst}
.. py:data:: LLDB_OPT_SET_11
+```
-Miscellaneous constants
-------------------------
+### Miscellaneous constants
+```{eval-rst}
.. py:data:: LLDB_GENERIC_ERROR
+```
+
+```{eval-rst}
.. py:data:: LLDB_DEFAULT_BREAK_SIZE
+```
+
+```{eval-rst}
.. py:data:: LLDB_WATCH_TYPE_READ
-.. py:data:: LLDB_WATCH_TYPE_WRITE
+```
+```{eval-rst}
+.. py:data:: LLDB_WATCH_TYPE_WRITE
-Enumerators
-***********
+```
+## Enumerators
-.. _State:
+(state)=
-State
------
+### State
+```{eval-rst}
.. py:data:: eStateInvalid
+```
+
+```{eval-rst}
.. py:data:: eStateUnloaded
Process is object is valid, but not currently loaded.
+```
+```{eval-rst}
.. py:da...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/201674
More information about the lldb-commits
mailing list