Author: Raphael Isemann Date: 2021-01-18T19:08:19+01:00 New Revision: a58aceffad61ebffb1a860763299b3307041efa6
URL: https://github.com/llvm/llvm-project/commit/a58aceffad61ebffb1a860763299b3307041efa6 DIFF: https://github.com/llvm/llvm-project/commit/a58aceffad61ebffb1a860763299b3307041efa6.diff LOG: [lldb][docs] Use 'any' as the default role in LLDB's sphinx project sphinx processes text in backticks depending on what 'role' it has (e.g., `:code:\`blub\`` -> role is `code`). If no role is provided, the default role is taken which is right now using the default value of `content`. `content` only really makes the text cursive which isn't really useful for anything right now. Sphinx recommends using the `any` role by default [1] as that turns text in backticks without an explicit roles into some kind of smart reference. If we did this in LLDB, then we could just reference SB API classes by doing `\`SBValue\`` instead of typing out the rather verbose `:py:class:`/`:py:func:`/... role before each reference. This would be especially nice when writing the SB API docs itself as we constantly have to reference other classes. [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-any Reviewed By: JDevlieghere Differential Revision: https://reviews.llvm.org/D94899 Added: Modified: lldb/docs/conf.py lldb/docs/use/python.rst lldb/docs/use/variable.rst Removed: ################################################################################ diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py index b5b594538239..2c7cd5d94c1f 100644 --- a/lldb/docs/conf.py +++ b/lldb/docs/conf.py @@ -98,8 +98,9 @@ # directories to ignore when looking for source files. exclude_patterns = ['_build', 'analyzer'] -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None +# Use the recommended 'any' rule so that referencing SB API classes is possible +# by just writing `SBData`. +default_role = 'any' # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True diff --git a/lldb/docs/use/python.rst b/lldb/docs/use/python.rst index 6b2125705086..efbe0d732c12 100644 --- a/lldb/docs/use/python.rst +++ b/lldb/docs/use/python.rst @@ -110,10 +110,10 @@ kind of Python variable will it be? The answers are to use the LLDB API functions, provided as part of the LLDB Python module. Running Python from inside LLDB, LLDB will automatically give us our current frame object as a Python variable, "lldb.frame". This variable has the type -"SBFrame" (see the LLDB API for more information about SBFrame +`SBFrame` (see the LLDB API for more information about `SBFrame` objects). One of the things we can do with a frame object, is to ask it to find and return its local variable. We will call the API function -"FindVariable" on the lldb.frame object to give us our dictionary +`SBFrame.FindVariable` on the lldb.frame object to give us our dictionary variable as a Python variable: :: @@ -125,11 +125,11 @@ current frame to find the variable named "dictionary" and return it. We then store the returned value in the Python variable named "root". This answers the question of HOW to get the variable, but it still doesn't explain WHAT actually gets put into "root". If you examine the LLDB API, you will find that the -SBFrame method "FindVariable" returns an object of type SBValue. SBValue +`SBFrame` method "FindVariable" returns an object of type `SBValue`. `SBValue` objects are used, among other things, to wrap up program variables and values. -There are many useful methods defined in the SBValue class to allow you to get +There are many useful methods defined in the `SBValue` class to allow you to get 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 +the header file SBValue.h. The `SBValue` methods that we use in our DFS function are ``GetChildMemberWithName()``, ``GetSummary()``, and ``GetValue()``. diff --git a/lldb/docs/use/variable.rst b/lldb/docs/use/variable.rst index ae6dbf2f4e5e..b9bcdf57cdde 100644 --- a/lldb/docs/use/variable.rst +++ b/lldb/docs/use/variable.rst @@ -677,7 +677,7 @@ passed two parameters: ``valobj`` and ``internal_dict``. not touch it. ``valobj`` is the object encapsulating the actual variable being displayed, and -its type is SBValue. Out of the many possible operations on an SBValue, the +its type is `SBValue`. Out of the many possible operations on an `SBValue`, the basic one is retrieve the children objects it contains (essentially, the fields of the object wrapped by it), by calling ``GetChildMemberWithName()``, passing it the child's name as a string. @@ -685,15 +685,15 @@ it the child's name as a string. If the variable has a value, you can ask for it, and return it as a string using ``GetValue()``, or as a signed/unsigned number using ``GetValueAsSigned()``, ``GetValueAsUnsigned()``. It is also possible to -retrieve an SBData object by calling ``GetData()`` and then read the object's -contents out of the SBData. +retrieve an `SBData` object by calling ``GetData()`` and then read the object's +contents out of the `SBData`. If you need to delve into several levels of hierarchy, as you can do with summary strings, you can use the method ``GetValueForExpressionPath()``, passing it an expression path just like those you could use for summary strings (one of the diff erences is that dereferencing a pointer does not occur by prefixing the path with a ``*```, but by calling the ``Dereference()`` method -on the returned SBValue). If you need to access array slices, you cannot do +on the returned `SBValue`). If you need to access array slices, you cannot do that (yet) via this method call, and you must use ``GetChildAtIndex()`` querying it for the array items one by one. Also, handling custom formats is something you have to deal with on your own. @@ -874,9 +874,9 @@ update. implementing it in terms of num_children is acceptable, implementors are encouraged to look for optimized coding alternatives whenever reasonable. -[3] This method is optional (starting with SVN revision 219330). The SBValue +[3] This method is optional (starting with SVN revision 219330). The `SBValue` you return here will most likely be a numeric type (int, float, ...) as its -value bytes will be used as-if they were the value of the root SBValue proper. +value bytes will be used as-if they were the value of the root `SBValue` proper. As a shortcut for this, you can inherit from lldb.SBSyntheticValueProvider, and just define get_value as other methods are defaulted in the superclass as returning default no-children responses. @@ -913,7 +913,7 @@ especially want to begin looking at this example to get a feel for this feature, as it is a very easy and well commented example. The design pattern consistently used in synthetic providers shipping with LLDB -is to use the __init__ to store the SBValue instance as a part of self. The +is to use the __init__ to store the `SBValue` instance as a part of self. The update function is then used to perform the actual initialization. Once a synthetic children provider is written, one must load it into LLDB before it can be used. Currently, one can use the LLDB script command to type Python code _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits