Automate building RST files for ReadTheDocs

Build the `.rst` files required to generate the API docs in ReadTheDocs. Although these files can be generated through a CLI flag, they are not built automatically during RTD generation. As inspired by this comment (readthedocs/readthedocs.org#1139 (comment)), add configuration steps to build the files automatically. This build avoids the need to commit the RST files to the repo.

docs/conf.py

@@ -206,3 +206,32 @@
 napoleon_use_ivar = True
 napoleon_use_param = True
 napoleon_use_rtype = True
+
+
+# automate building API .rst files, necessary for ReadTheDocs, as inspired by:
+# https://github.com/readthedocs/readthedocs.org/issues/1139#issuecomment-398083449
+def run_apidoc(_):
+    ignore_paths = []
+
+    argv = [
+        "-f",
+        "-T",
+        "-e",
+        "-M",
+        "-o", ".",
+        ".."
+    ] + ignore_paths
+
+    try:
+        # Sphinx >= 1.7
+        from sphinx.ext import apidoc
+        apidoc.main(argv)
+    except ImportError:
+        # Sphinx  < 1.7
+        from sphinx import apidoc
+        argv.insert(0, apidoc.__file__)
+        apidoc.main(argv)
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)