[lldb][docs] Use 'any' as the default role in LLDB's sphinx project

[teemperor]

Summary

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

[JDevlieghere]

Cool. That was one of the reasons I suggested having the SB API documentation integrated with the rest of the docs.

lldb/docs/conf.py

 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # 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
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 

lldb/docs/use/python.rst

 
 The most interesting parameter is the first one, the Python variable
 that needs to contain a node in our search tree. How can we take a
 variable out of our program and put it into a Python variable? What
 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:
 
 ::
 
    root = lldb.frame.FindVariable ("dictionary")
 
 The line above, executed in the Python script interpreter in LLDB, asks the
 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()``.
 
 
 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

lldb/docs/use/variable.rst

 
 As a brief introduction, your script is encapsulated into a function that is
 passed two parameters: ``valobj`` and ``internal_dict``.
 
 ``internal_dict`` is an internal support parameter used by LLDB and you should
 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.
 
 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 differences 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.
 
 ``options`` Python summary formatters can optionally define this
 third argument, which is an object of type ``lldb.SBTypeSummaryOptions``,
 allowing for a few customizations of the result. The decision to
 adopt or not this third argument - and the meaning of options 

 nothing, None, or anything other than True is returned, LLDB will discard the
 cached information and ask. Regardless, whenever necessary LLDB will call
 update.
 
 [2] This method is optional (starting with SVN rev166495/LLDB-175). While
 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.
 
 If a synthetic child provider supplies a special child named
 ``$$dereference$$`` then it will be used when evaluating ``operator *`` and
 ``operator ->`` in the frame variable command and related SB API
 functions. It is possible to declare this synthetic child without

 
 For examples of how synthetic children are created, you are encouraged to look
 at examples/synthetic in the LLDB trunk. Please, be aware that the code in
 those files (except bitfield/) is legacy code and is not maintained. You may
 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
 interactively, or use the command script import fileName command to load Python
 code from a Python module (ordinary rules apply to importing modules this way).
 A third option is to type the code for the provider class interactively while
 adding it.