From 0d80a54958ea0bc20b78dc323ac246af1b6d0814 Mon Sep 17 00:00:00 2001
From: Cody Wang <speller26@gmail.com>
Date: Fri, 14 Aug 2020 14:30:11 -0700
Subject: [PATCH] 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     | 2 ++
 doc/conf.py          | 8 ++++++++
 doc/requirements.txt | 1 +
 setup.py             | 1 +
 tox.ini              | 2 +-
 5 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index d40e9b4f..26bc27fa 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -17,4 +17,6 @@ formats:
 python:
   version: 3.7
   install:
+    - method: pip
+      path: .
     - requirements: doc/requirements.txt
diff --git a/doc/conf.py b/doc/conf.py
index eef5243d..e309d41b 100644
--- a/doc/conf.py
+++ b/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 -------------------------------------------
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
index cbf1e365..bf1b2d65 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,2 +1,3 @@
 sphinx
 sphinx-rtd-theme
+sphinxcontrib-apidoc
diff --git a/setup.py b/setup.py
index 46e9ab12..725897b5 100644
--- a/setup.py
+++ b/setup.py
@@ -42,6 +42,7 @@
             "pytest-xdist",
             "sphinx",
             "sphinx-rtd-theme",
+            "sphinxcontrib-apidoc",
             "tox",
         ]
     },
diff --git a/tox.ini b/tox.ini
index 01868022..7bf5d826 100644
--- a/tox.ini
+++ b/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]