Consider using sphinx-autoapi to generate docs without having to import rubicon.objc

[dgelessus]

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.

[samschott]

I've made some good experiences with sphinx-autoapi for such use cases. The only issues which I have found:

1. The support for moving type hints to the doc string is a bit flaky at the moment.
2. Some cross references may not work unless you use a fully qualified path.

Otherwise it is very reliable and supports similar rst syntax as autodoc for generating class and module docs.

[freakboy3742]

I've take a quick look at this - there's an additional complication in that some of the type definitions (CGFloat is the first one that is discovered) can't be resolved because they require execution of the code.