[Lldb-commits] [lldb] 3ebfeb2 - [lldb][docs] Force documentation emission of special Python class members

[Raphael Isemann via lldb-commits]

Author: Raphael Isemann
Date: 2021-07-07T19:49:50+02:00
New Revision: 3ebfeb258698db82b7525cfaa1efd04db93d72ba

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

LOG: [lldb][docs] Force documentation emission of special Python class members

The current LLDB Python docs are missing documentation for all the special
members such as conversion functions (`__int__`) and other special functions
(`__len__`).

The reason for that is that the `automodapi` plugin we're using to generate the
*.rst files simply doesn't emit them. There doesn't seem to be any config option
to enable those in `automodapi` and it's not even clear why they are filtered. I
assume the leading underscore in their names makes them look like private
methods.

This patch just forcibly adds a few selected special members functions to the
list of functions that sphinx should always document.  This will cause sphinx to
warn if a class doesn't have one of those functions but it's better than not
having them documented.

The main motivation here is that since `SBAddress.__int__` is one of the few
functions that is only available in the embedded Python REPL which would be good
to have in the public documentation.

Fixes rdar://64647665

Reviewed By: JDevlieghere

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

Added: 
    

Modified: 
    lldb/docs/conf.py

Removed: 
    


################################################################################
diff  --git a/lldb/docs/conf.py b/lldb/docs/conf.py
index b614f43f55c00..0c3cd59fc11ef 100644
--- a/lldb/docs/conf.py
+++ b/lldb/docs/conf.py
@@ -44,6 +44,10 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
 
+autodoc_default_options = {
+    'special-members': '__int__, __len__, __hex__, __oct__, __iter__',
+}
+
 # Unless we only generate the basic manpage we need the plugin for generating
 # the Python API documentation.
 if not building_man_page: