[Lldb-commits] [lldb] 3c69ff4 - [lldb][docs] Filter out 'thisown' attribute and inheritance boilerplate

[Raphael Isemann via lldb-commits]

Author: Raphael Isemann
Date: 2021-01-20T09:07:36+01:00
New Revision: 3c69ff4b03abaa3b7b80f4f3f2a1c1806e2d4495

URL: https://github.com/llvm/llvm-project/commit/3c69ff4b03abaa3b7b80f4f3f2a1c1806e2d4495
DIFF: https://github.com/llvm/llvm-project/commit/3c69ff4b03abaa3b7b80f4f3f2a1c1806e2d4495.diff

LOG: [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

Added: 
    

Modified: 
    lldb/docs/conf.py

Removed: 
    


################################################################################
diff  --git a/lldb/docs/conf.py b/lldb/docs/conf.py
index 2c7cd5d94c1f..b9b94672cbde 100644
--- a/lldb/docs/conf.py
+++ b/lldb/docs/conf.py
@@ -298,3 +298,36 @@ def process_md(name):
 
 # 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)