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

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.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94967

diff --git a/lldb/docs/conf.py b/lldb/docs/conf.py
index 2c7cd5d..b9b9467 100644 (file)
--- a/lldb/docs/conf.py
+++ b/lldb/docs/conf.py
@@ -298,3 +298,36 @@ texinfo_documents = [
 
 # 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)