documentation: Get Read the Docs working (#46)

Fixed previously failing Read the Docs builds by:
1. Explicity adding `method` and `path` to .readthedocs.yml; this was causing builds to fail altogether
2. Using [sphinxcontrib-apidoc](https://github.com/sphinx-contrib/apidoc) instead autodoc directly (see readthedocs/readthedocs.org#1139). Defore, our `tox -e docs` command would run `aphinx-apidoc` then `sphinx-build`. However, Read the Docs only runs `sphinx-build`, so the module docs would never get generated.

.readthedocs.yml

@@ -17,4 +17,6 @@ formats:
 python:
   version: 3.7
   install:
+    - method: pip
+      path: .
     - requirements: doc/requirements.txt

doc/conf.py

@@ -10,6 +10,7 @@
 copyright = "{}, Amazon.com".format(datetime.datetime.now().year)
 
 extensions = [
+    "sphinxcontrib.apidoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
@@ -29,6 +30,13 @@
 
 napoleon_use_rtype = False
 
+apidoc_module_dir = "../src/braket"
+apidoc_output_dir = "_apidoc"
+apidoc_excluded_paths = ["../test"]
+apidoc_separate_modules = True
+apidoc_module_first = True
+apidoc_extra_args = ["-f", "--implicit-namespaces", "-H", "API Reference"]
+
 
 # -- Options for MathJax output -------------------------------------------
 

doc/requirements.txt

@@ -1,2 +1,3 @@
 sphinx
 sphinx-rtd-theme
+sphinxcontrib-apidoc

setup.py

@@ -42,6 +42,7 @@
             "pytest-xdist",
             "sphinx",
             "sphinx-rtd-theme",
+            "sphinxcontrib-apidoc",
             "tox",
         ]
     },

tox.ini

@@ -53,8 +53,8 @@ basepython = python3.7
 deps =
     sphinx
     sphinx-rtd-theme
+    sphinxcontrib-apidoc
 commands =
-    sphinx-apidoc -e -f -M --implicit-namespaces -H "API Reference" -o doc/_apidoc src/braket
     sphinx-build -E -T -b html doc build/documentation/html
 
 [testenv:serve-docs]