docs: Update conf to build again.

The conf was out of date on libraries including the version of sphinx.
So in order to use the edx theme, I updated sphinx and then correct the
conf.py to generate docs including configuring django sufficiently.

Author: feanil

docs/api/source/conf.py

@@ -1,11 +1,10 @@
 import os
 import sys
+import django
 
-from path import path
+from path import Path
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
-# sys.path.insert(0, os.path.abspath('..'))
+import edx_theme
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path.append('source/_templates')
@@ -15,38 +14,48 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path.append('source/_static')
 
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
 master_doc = 'index'
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-root = path('../../..').abspath()
+root = Path('../../..').abspath()
 sys.path.insert(0, root)
 sys.path.append(root / "analytics_data_api/v0/views")
 sys.path.append('.')
 
 # -- General configuration -----------------------------------------------------
 
 #  django configuration  - careful here
-if on_rtd:
-    os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
-else:
-    os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
+os.environ['DJANGO_SETTINGS_MODULE'] = 'analyticsdataserver.settings.local'
+django.setup()
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'edx_theme',
     'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
-    'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
+    'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.imgmath',
     'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ['build', 'links.rst']
 
-project = 'Open edX Data Analytics API Version 0 Alpha'
-copyright = '2015, edX'
+project = 'Open edX Data Analytics API'
+copyright = '2021, edX'
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'edx_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [edx_theme.get_html_theme_path()]

requirements/doc.in

@@ -2,4 +2,6 @@
 
 -r base.in                          # Core dependencies of edx-analytics-data-api
 
-Sphinx==1.2.1                       # Developer documentation builder
+Sphinx                              # Developer documentation builder
+path
+edx_sphinx_theme

requirements/doc.txt

@@ -4,6 +4,10 @@
 #
 #    make upgrade
 #
+alabaster==0.7.12
+    # via sphinx
+babel==2.9.1
+    # via sphinx
 boto==2.42.0
     # via -r requirements/base.in
 boto3==1.18.18
@@ -116,6 +120,8 @@ edx-rest-api-client==5.4.0
     # via
     #   -r requirements/base.in
     #   edx-enterprise-data
+edx-sphinx-theme==3.0.0
+    # via -r requirements/doc.in
 elasticsearch==7.14.0
     # via elasticsearch-dsl
 elasticsearch-dsl==7.4.0
@@ -126,6 +132,8 @@ future==0.18.2
     # via pyjwkest
 idna==3.2
     # via requests
+imagesize==1.2.0
+    # via sphinx
 itypes==1.2.0
     # via coreapi
 jinja2==3.0.1
@@ -148,6 +156,10 @@ ordered-set==3.1.1
     # via
     #   -c requirements/constraints.txt
     #   -r requirements/base.in
+packaging==21.0
+    # via sphinx
+path==16.2.0
+    # via -r requirements/doc.in
 pbr==5.6.0
     # via stevedore
 psutil==5.8.0
@@ -167,6 +179,8 @@ pyjwt[crypto]==2.1.0
     #   edx-rest-api-client
 pymongo==3.12.0
     # via edx-opaque-keys
+pyparsing==2.4.7
+    # via packaging
 python-dateutil==2.8.2
     # via
     #   botocore
@@ -175,7 +189,9 @@ python-dateutil==2.8.2
 python-memcached==1.59
     # via -r requirements/base.in
 pytz==2021.1
-    # via django
+    # via
+    #   babel
+    #   django
 pyyaml==5.4.1
     # via edx-django-release-util
 requests==2.26.0
@@ -186,6 +202,7 @@ requests==2.26.0
     #   edx-rest-api-client
     #   pyjwkest
     #   slumber
+    #   sphinx
 rest-condition==1.0.3
     # via edx-drf-extensions
 rules==3.0
@@ -203,14 +220,31 @@ six==1.16.0
     #   edx-django-release-util
     #   edx-drf-extensions
     #   edx-rbac
+    #   edx-sphinx-theme
     #   elasticsearch-dsl
     #   pyjwkest
     #   python-dateutil
     #   python-memcached
 slumber==0.7.1
     # via edx-rest-api-client
-sphinx==1.2.1
-    # via -r requirements/doc.in
+snowballstemmer==2.1.0
+    # via sphinx
+sphinx==4.1.2
+    # via
+    #   -r requirements/doc.in
+    #   edx-sphinx-theme
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.0
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
 sqlparse==0.4.1
     # via django
 stevedore==3.3.0
@@ -229,3 +263,6 @@ urllib3==1.26.6
     #   botocore
     #   elasticsearch
     #   requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools