[llvm-branch-commits] [lldb] a58acef - [lldb][docs] Use 'any' as the default role in LLDB's sphinx project

[Raphael Isemann via llvm-branch-commits]

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