[Lldb-commits] [lldb] b1ef2db - [lldb][docs] Fix header level warnings in a few documents
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Tue Dec 9 04:50:18 PST 2025
Author: David Spickett
Date: 2025-12-09T12:49:19Z
New Revision: b1ef2db4c681680d969c0e7d280b0e469ba877a9
URL: https://github.com/llvm/llvm-project/commit/b1ef2db4c681680d969c0e7d280b0e469ba877a9
DIFF: https://github.com/llvm/llvm-project/commit/b1ef2db4c681680d969c0e7d280b0e469ba877a9.diff
LOG: [lldb][docs] Fix header level warnings in a few documents
All these are using H1 for the main heading but H3 for the
rest, Sphinx warns about this:
WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
Added:
Modified:
lldb/docs/use/tutorials/creating-custom-breakpoints.md
lldb/docs/use/tutorials/implementing-standalone-scripts.md
lldb/docs/use/tutorials/script-driven-debugging.md
lldb/docs/use/tutorials/writing-custom-commands.md
Removed:
################################################################################
diff --git a/lldb/docs/use/tutorials/creating-custom-breakpoints.md b/lldb/docs/use/tutorials/creating-custom-breakpoints.md
index 04673c310ccf3..b31a600a7505a 100644
--- a/lldb/docs/use/tutorials/creating-custom-breakpoints.md
+++ b/lldb/docs/use/tutorials/creating-custom-breakpoints.md
@@ -20,7 +20,7 @@ happens when a location triggers and includes the commands, conditions, ignore
counts, etc. Stop options are common between all breakpoint types, so for our
purposes only the Searcher and Resolver are relevant.
-### Breakpoint Searcher
+## Breakpoint Searcher
The Searcher's job is to traverse in a structured way the code in the current
target. It proceeds from the Target, to search all the Modules in the Target,
@@ -36,7 +36,7 @@ based search filter. If neither of these is specified, the breakpoint will have
a no-op search filter, so all parts of the program are searched and all
locations accepted.
-### Breakpoint Resolver
+## Breakpoint Resolver
The Resolver has two functions:
@@ -72,7 +72,7 @@ you add to the breakpoint yourself. Note that the Breakpoint takes care of
deduplicating equal addresses in AddLocation, so you shouldn't need to worry
about that anyway.
-### Scripted Breakpoint Resolver
+## Scripted Breakpoint Resolver
At present, when adding a ScriptedBreakpoint type, you can only provide a
custom Resolver, not a custom SearchFilter.
@@ -127,7 +127,7 @@ of Modules and the list of CompileUnits that will make up the SearchFilter. If
you pass in empty lists, the breakpoint will use the default "search
everywhere,accept everything" filter.
-### Providing Facade Locations:
+## Providing Facade Locations:
The breakpoint resolver interface also allows you to present a separate set
of locations for the breakpoint than the ones that actually implement the
diff --git a/lldb/docs/use/tutorials/implementing-standalone-scripts.md b/lldb/docs/use/tutorials/implementing-standalone-scripts.md
index b1a3441ffe2ee..8143bb8990768 100644
--- a/lldb/docs/use/tutorials/implementing-standalone-scripts.md
+++ b/lldb/docs/use/tutorials/implementing-standalone-scripts.md
@@ -1,6 +1,6 @@
# Implementing Standalone Scripts
-### Configuring `PYTHONPATH`
+## Configuring `PYTHONPATH`
LLDB has all of its core code built into a shared library which gets used by
the `lldb` command line application.
@@ -30,7 +30,7 @@ $ export PYTHONPATH=`lldb -P`
Alternatively, you can append the LLDB Python directory to the sys.path list
directly in your Python code before importing the lldb module.
-### Initialization
+## Initialization
The standard test for `__main__`, like many python modules do, is useful for
creating scripts that can be run from the command line. However, for command
@@ -56,7 +56,7 @@ if __name__ == '__main__':
lldb.SBDebugger.Terminate()
```
-### Example
+## Example
Now your python scripts are ready to import the lldb module. Below is a python
script that will launch a program from the current working directory called
@@ -133,7 +133,7 @@ if target:
print(symbol)
```
-### Expected Output
+## Expected Output
Exact output varies by system, but you should see something like this:
@@ -148,7 +148,7 @@ a.out[0x714]: mov w0, #0x0 ; =0
a.out[0x718]: ret
```
-### Troubleshooting
+## Troubleshooting
You can use all the usual Python tools to debug scripts, and on top of that
you can enable LLDB's log channels. To do this in the script shown above, add
diff --git a/lldb/docs/use/tutorials/script-driven-debugging.md b/lldb/docs/use/tutorials/script-driven-debugging.md
index 0e93e869923a6..4fe3ef8281f84 100644
--- a/lldb/docs/use/tutorials/script-driven-debugging.md
+++ b/lldb/docs/use/tutorials/script-driven-debugging.md
@@ -12,7 +12,7 @@ This document will show how to do some of these things by going through an
example, explaining how to use Python scripting to find a bug in a program
that searches for text in a large binary tree.
-### The Test Program and Input
+## The Test Program and Input
We have a simple C program ([dictionary.c](https://github.com/llvm/llvm-project/blob/main/lldb/examples/scripting/dictionary.c))
that reads in a text file, and stores all the words from the file in a
@@ -24,7 +24,7 @@ the word in the tree.
The input text file we are using to test our program contains the text
for William Shakespeare's famous tragedy "Romeo and Juliet".
-### The Bug
+## The Bug
When we try running our program, we find there is a problem. While it
successfully finds some of the words we would expect to find, such as
@@ -44,7 +44,7 @@ Enter search word: ^D
$
```
-### Using Depth First Search
+## Using Depth First Search
Our first job is to determine if the word "Romeo" actually got inserted
into the tree or not. Since "Romeo and Juliet" has thousands of words,
@@ -86,7 +86,7 @@ later explanations:
25: return DFS (right_child_ptr, word, cur_path)
```
-### Accessing & Manipulating Program Variables
+## Accessing & Manipulating Program Variables
Before we can call any Python function on any of our program's
variables, we need to get the variable into a form that Python can
@@ -126,7 +126,7 @@ information or children values out of SBValues. For complete information, see
the header file SBValue.h. The `SBValue` methods that we use in our DFS function
are `GetChildMemberWithName()`, `GetSummary()`, and `GetValue()`.
-### Explaining DFS Script in Detail
+## Explaining DFS Script in Detail
Before diving into the details of this code, it would be best to give a
high-level overview of what it does. The nodes in our binary search tree were
@@ -166,7 +166,7 @@ start all over. Therefore we recommend doing as we have done: Writing your
longer, more complicated script functions in a separate file (in this case
tree_utils.py) and then importing it into your LLDB Python interpreter.
-### The DFS Script in Action
+## The DFS Script in Action
At this point we are ready to use the DFS function to see if the word "Romeo"
is in our tree or not. To actually use it in LLDB on our dictionary program,
@@ -261,7 +261,7 @@ From this we can see that the word "Romeo" was indeed found in the tree, and
the path from the root of the tree to the node containing "Romeo" is
left-left-right-right-left.
-### Using Breakpoint Command Scripts
+## Using Breakpoint Command Scripts
We are halfway to figuring out what the problem is. We know the word we are
looking for is in the binary tree, and we know exactly where it is in the
@@ -282,7 +282,7 @@ being hit. But if the decision
diff ers from what the path says it should be,
then the script prints out a message and does NOT resume execution, leaving the
user sitting at the first point where a wrong decision is being made.
-### Python Breakpoint Command Scripts Are Not What They Seem
+## Python Breakpoint Command Scripts Are Not What They Seem
What do we mean by that? When you enter a Python breakpoint command in LLDB, it
appears that you are entering one or more plain lines of Python. BUT LLDB then
@@ -305,7 +305,7 @@ automatically have a frame and a bp_loc variable. The variables are pre-loaded
by LLDB with the correct context for the breakpoint. You do not have to use
these variables, but they are there if you want them.
-### The Decision Point Breakpoint Commands
+## The Decision Point Breakpoint Commands
This is what the Python breakpoint command script would look like for the
decision to go right:
@@ -358,7 +358,7 @@ execution. We allow the breakpoint to remain stopped (by doing nothing), and we
print an informational message telling the user we have found the problem, and
what the problem is.
-### Actually Using The Breakpoint Commands
+## Actually Using The Breakpoint Commands
Now we will look at what happens when we actually use these breakpoint commands
on our program. Doing a source list -n find_word shows us the function
@@ -480,7 +480,7 @@ case conversion problem somewhere in our program (we do).
This is the end of our example on how you might use Python scripting in LLDB to
help you find bugs in your program.
-### Sources
+## Sources
The complete code for the Dictionary program (with case-conversion bug), the
DFS function and other Python script examples used for this example are
diff --git a/lldb/docs/use/tutorials/writing-custom-commands.md b/lldb/docs/use/tutorials/writing-custom-commands.md
index 0b1d105f4a52f..1ec6edf7a18c4 100644
--- a/lldb/docs/use/tutorials/writing-custom-commands.md
+++ b/lldb/docs/use/tutorials/writing-custom-commands.md
@@ -1,6 +1,6 @@
# Writing Custom Commands
-### Create a new command using a Python function
+## Create a new command using a Python function
Python functions can be used to create new LLDB command interpreter commands,
which will work like all the natively defined lldb commands. This provides a
@@ -51,7 +51,7 @@ command definition form can't do the right thing.
| `result` | `lldb.SBCommandReturnObject` | A return object which encapsulates success/failure information for the command and output text that needs to be printed as a result of the command. The plain Python "print" command also works but text won't go in the result by default (it is useful as a temporary logging facility). |
| `internal_dict` | `python dict object` | The dictionary for the current embedded script session which contains all variables and functions. |
-### Create a new command using a Python class
+## Create a new command using a Python class
Since lldb 3.7, Python commands can also be implemented by means of a class
which should implement the following interface:
@@ -103,7 +103,7 @@ print("my command does lots of cool stuff", file=result)
`SBCommandReturnObject` and `SBStream` both support this file-like behavior by
providing `write()` and `flush()` calls at the Python layer.
-### Parsed Commands
+## Parsed Commands
The commands that are added using this class definition are what lldb calls
"raw" commands. The command interpreter doesn't attempt to parse the command,
@@ -207,7 +207,7 @@ Mostly useful for handle_completion where you get passed the long option.
"""
```
-### Completion
+## Completion
lldb will handle completing your option names, and all your enum values
automatically. If your option or argument types have associated built-in completers,
@@ -280,7 +280,7 @@ You can optionally include a "descriptions" key, whose value is a parallel array
of description strings, and the completion will show the description next to
each completion.
-### Loading Commands
+## Loading Commands
One other handy convenience when defining lldb command-line commands is the
command "command script import" which will import a module specified by file
@@ -309,7 +309,7 @@ def goodstuff(debugger, command, ctx, result, internal_dict):
# Command Implementation code goes here
```
-### Examples
+## Examples
Now we can create a module called ls.py in the file ~/ls.py that will implement
a function that can be used by LLDB's python command code:
More information about the lldb-commits
mailing list