Merge pull request #190 from edx/feanil/docs_ci

docs: Build the docs as a part of CI.

.readthedocs.yml

@@ -0,0 +1,21 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+   - epub
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+   version: 3.8
+   install:
+   - requirements: requirements/doc.txt

.travis.yml

@@ -3,6 +3,7 @@ python:
   - '3.8'
 env:
   - TOXENV=quality
+  - TOXENV=docs
   - TOXENV=without-django
   - TOXENV=django22
   - TOXENV=django30

docs/conf.py

@@ -129,7 +129,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

opaque_keys/edx/keys.py

@@ -204,8 +204,10 @@ class UsageKeyV2(UsageKey):
     UsageKeyV2 is just a subclass of UsageKey with slightly different behavior,
     but not a distinct key type (same KEY_TYPE). UsageKeyV2 should be used for
     new usage key types; the main differences between it and UsageKey are:
+
         * the .course_key property is considered deprecated for the new V2 key
           types, and they should implement .context_key instead.
+
         * the .definition_key property is explicitly disabled for V2 usage keys
     """
     __slots__ = ()

opaque_keys/edx/locator.py

@@ -610,8 +610,11 @@ class BlockUsageLocator(BlockLocatorBase, UsageKey):
 
     BlockUsageLocators also support deprecated Location-style formatting with the following mapping:
     Location(org, course, run, category, name, revision) is represented as a BlockUsageLocator with:
+
       - course_key = a CourseKey comprised of (org, course, run, branch=revision)
+
       - block_type = category
+
       - block_id = name
     """
     CANONICAL_NAMESPACE = 'block-v1'

tox.ini

@@ -3,7 +3,7 @@ envlist =  py38-django{22,30,31,32},quality,without-django
 skip_missing_interpreters = True
 
 [testenv]
-deps = 
+deps =
 	django22: Django>=2.2,<2.3
 	django30: Django>=3.0,<3.1
 	django31: Django>=3.1,<3.2
@@ -12,12 +12,26 @@ deps =
 commands = pytest --disable-pytest-warnings --nomigrations {posargs}
 
 [testenv:without-django]
-deps = 
+deps =
 	-r{toxinidir}/requirements/test.txt
 commands = pytest --disable-pytest-warnings --ignore=opaque_keys/edx/django {posargs}
 
 [testenv:quality]
-commands = 
+commands =
 	pycodestyle --config=.pep8 opaque_keys
 	pylint --rcfile=pylintrc opaque_keys
 
+[testenv:docs]
+deps =
+    -r{toxinidir}/requirements/doc.txt
+allowlist_externals =
+    make
+    env
+setenv =
+# -W will treat warnings as errors.
+    SPHINXOPTS = -W
+commands =
+# -e allows for overriding setting from the environment.
+# -C changes the directory to `docs` before running the command.
+    make -e -C docs clean
+    make -e -C docs html