Description
Many parts of our reference documentation are generated using the Sphinx autodoc extension, which includes contents of docstrings from our Python code into the documentation. To extract the docstrings, autodoc imports the modules in question and reads the __doc__ attributes at runtime.
Unfortunately, this causes some problems with Rubicon, because even just importing rubicon.objc requires a working Objective-C runtime (to look up Objective-C runtime functions and core classes like NSObject), which isn't available in documentation building environments like Read the Docs. We were able to work around this issue by writing a mock version of ctypes and using it during the documentation build in place of the real ctypes module. This mock ctypes implements just enough APIs to make rubicon.objc import successfully and allow Sphinx to extract the docstrings. (See #150 and #154 for details.)
In the PR discussion I said:
It would be really nice if Sphinx autodoc could extract docstrings by statically parsing the code instead of importing/executing it, then we wouldn't have this issue...
It turns out that something like this exists: sphinx-autoapi. I haven't looked into it in detail or tried it yet, but it looks promising. It would be great if we could change our doc build to use this extension instead of regular Sphinx autodoc - then we could get rid of our custom mock ctypes version and wouldn't have to worry about runtime import problems anymore.