[lldb][docs] Filter out 'thisown' attribute and inheritance boilerplate

[teemperor]

Summary

This patch implements a filter that post-processes some of the generated RST sources
of the Python API docs. I mainly want to avoid two things:

1. Filter out all the inheritance boilerplate that just keeps mentioning for every class that it inherits from the builtin 'object'. There is no inheritance in the SB API.
2. More importantly, removes the SWIG generated thisown attribute from the public documentation. I don't think we want users to mess with that attribute and this is probably causing more confusion than it would help anyone. It also makes the documentation for some smaller classes more verbose than necessary.

This patch just uses the sphinx event for reading source and removes the parts that we don't want in documentation.

[JDevlieghere]

lldb/docs/conf.py

316

How often is this called? If the answer is "a lot" then maybe a re.compile outside this function would be appropriate?

[teemperor]

• Compile regex only once

lldb/docs/conf.py

316

Something like 30 times maybe? But maybe this will change in the future, so I moved out the compilation

[JDevlieghere]

LGTM

lldb/docs/conf.py

 # Documents to append as an appendix to all manuals.
 #texinfo_appendices = []
 
 # If false, no module index is generated.
 #texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+empty_attr_summary = re.compile(r'\.\. rubric:: Attributes Summary\s*\.\. autosummary::\s*\.\. rubric::')
+empty_attr_documentation = re.compile(r'\.\. rubric:: Attributes Documentation\s*\.\. rubric::')
+
+def cleanup_source(app, docname, source):
+    """ Cleans up source files generated by automodapi. """
+    # Don't cleanup anything beside automodapi-generated sources.
+    if not automodapi_toctreedirnm in docname:
+      return
+    processed = source[0]
+
+    # Don't show the list of inheritance info as there is no inheritance in the
+    # SBI API. This avoids all the repeated text on all doc pages that a
+    # class inherits from 'object'.
+
+    processed = processed.replace(":show-inheritance:", "")
+    # Remove the SWIG generated 'thisown' attribute. It just bloats the generated
+    # documentation and users shouldn't fiddle with the value anyway.
+    processed = re.sub(r'~SB[a-zA-Z]+\.thisown', "", processed)
+    processed = processed.replace("  .. autoattribute:: thisown", "")
+
+    # After removing 'thisown', many objects don't have any attributes left.
+    # Remove all now empty attribute summary/documentation sections with
+    # some rather ugly regex.
+    processed = empty_attr_summary.sub('.. rubric::', processed)
+    processed = empty_attr_documentation.sub('.. rubric::', processed)
+
+    # Replace the original source with the processed one (source is a single
+    # element list).
+    source[0] = processed
+
+def setup(app):
+    app.connect('source-read', cleanup_source)