Merge pull request #5491 from edx/markhoeber-doc989

WIP: edX Mobile API Doc

docs/en_us/platform_api/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+PAPER         ?=
+BUILDDIR      ?= build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+Q_FLAG        =
+
+ifeq ($(quiet), true)
+Q_FLAG = -Q
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = $(Q_FLAG) -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/edX.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/edX.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/edX"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/edX"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/en_us/platform_api/requirements.txt

+path.py
+Django >=1.4,<1.5
+pytz
+-e git+https://github.com/edx/XBlock.git#egg=XBlock
+lxml
+sphinxcontrib-napoleon==0.2.6
+stevedore==0.14.1
+djangorestframework==2.3.14
+PyYAML>=3.10

docs/en_us/platform_api/source/_templates/layout.html

+{% extends "!layout.html" %}
+
+{% block header %}
+<img src="{{ pathto("_static/homepage-bg.jpg", 1) }}" alt="Edx logo"  width="100%;"/>
+{% endblock %}
\ No newline at end of file

docs/en_us/platform_api/source/authentication.rst

+.. _edX API Authentication:
+
+#############################
+edX API Authentication
+#############################
+
+
+*************
+OAuth 2.0
+*************
+
+The edX Platform API uses OAuth 2.0 for authentication.  OAuth 2.0 is an open
+standard used by many systems that require secure user authentication. See the
+`OAuth 2.0 Standard`_ standard for more information.
+
+
+***************************************
+Registering with Your Open edX Instance
+***************************************
+
+To use the edX Platform API with courses on you instance of Open edX, you must register your application with the Open edX server. See the OAuth 2.0 specification for details.
+
+.. include:: links.rst
\ No newline at end of file

docs/en_us/platform_api/source/conf.py

+# -*- coding: utf-8 -*-
+# pylint: disable=C0103
+# pylint: disable=W0622
+# pylint: disable=W0212
+# pylint: disable=W0613
+
+import sys, os
+from path import path
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+sys.path.append('../../../../')
+
+from docs.shared.conf import *
+
+
+# Add any paths that contain templates here, relative to this directory.
+#templates_path.append('source/_templates')
+
+
+# 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.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()]
+
+
+# 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()
+sys.path.insert(0, root)
+sys.path.append(root / "lms/djangoapps/mobile_api")
+sys.path.append(root / "lms/djangoapps/mobile_api/course_info")
+sys.path.append(root / "lms/djangoapps/mobile_api/users")
+sys.path.append(root / "lms/djangoapps/mobile_api/video_outlines")
+
+sys.path.insert(0, os.path.abspath(os.path.normpath(os.path.dirname(__file__)
+    + '/../../../')))
+sys.path.append('.')
+
+#  django configuration  - careful here
+if on_rtd:
+    os.environ['DJANGO_SETTINGS_MODULE'] = 'lms'
+else:
+    os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.test'
+
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
+    'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
+    'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['build']
+
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'edXDocs'
+
+project = u'edX Platform API Version 0.5 Alpha'
+copyright = u'2014, edX'
+
+# --- Mock modules ------------------------------------------------------------
+
+# Mock all the modules that the readthedocs build can't import
+
+class Mock(object):
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __call__(self, *args, **kwargs):
+        return Mock()
+
+    @classmethod
+    def __getattr__(cls, name):
+        if name in ('__file__', '__path__'):
+            return '/dev/null'
+        elif name[0] == name[0].upper():
+            mockType = type(name, (), {})
+            mockType.__module__ = __name__
+            return mockType
+        else:
+            return Mock()
+
+# The list of modules and submodules that we know give RTD trouble.
+# Make sure you've tried including the relevant package in
+# docs/share/requirements.txt before adding to this list.
+MOCK_MODULES = [
+    'bson',
+    'bson.errors',
+    'bson.objectid',
+    'dateutil',
+    'dateutil.parser',
+    'fs',
+    'fs.errors',
+    'fs.osfs',
+    'lazy',
+    'mako',
+    'mako.template',
+    'matplotlib',
+    'matplotlib.pyplot',
+    'mock',
+    'numpy',
+    'oauthlib',
+    'oauthlib.oauth1',
+    'oauthlib.oauth1.rfc5849',
+    'PIL',
+    'pymongo',
+    'pyparsing',
+    'pysrt',
+    'requests',
+    'scipy.interpolate',
+    'scipy.constants',
+    'scipy.optimize',
+    'yaml',
+    'webob',
+    'webob.multidict',
+    ]
+
+if on_rtd:
+    for mod_name in MOCK_MODULES:
+        sys.modules[mod_name] = Mock()
+
+# -----------------------------------------------------------------------------
+
+# from http://djangosnippets.org/snippets/2533/
+# autogenerate models definitions
+
+import inspect
+import types
+from HTMLParser import HTMLParser
+
+
+def force_unicode(s, encoding='utf-8', strings_only=False, errors='strict'):
+    """
+    Similar to smart_unicode, except that lazy instances are resolved to
+    strings, rather than kept as lazy objects.
+
+    If strings_only is True, don't convert (some) non-string-like objects.
+    """
+    if strings_only and isinstance(s, (types.NoneType, int)):
+        return s
+    if not isinstance(s, basestring,):
+        if hasattr(s, '__unicode__'):
+            s = unicode(s)
+        else:
+            s = unicode(str(s), encoding, errors)
+    elif not isinstance(s, unicode):
+        s = unicode(s, encoding, errors)
+    return s
+
+
+class MLStripper(HTMLParser):
+    def __init__(self):
+        self.reset()
+        self.fed = []
+
+    def handle_data(self, d):
+        self.fed.append(d)
+
+    def get_data(self):
+        return ''.join(self.fed)
+
+
+def strip_tags(html):
+    s = MLStripper()
+    s.feed(html)
+    return s.get_data()
+
+
+
+def process_docstring(app, what, name, obj, options, lines):
+    """Autodoc django models"""
+
+    # This causes import errors if left outside the function
+    from django.db import models
+
+    # If you want extract docs from django forms:
+    # from django import forms
+    # from django.forms.models import BaseInlineFormSet
+
+    # Only look at objects that inherit from Django's base MODEL class
+    if inspect.isclass(obj) and issubclass(obj, models.Model):
+        # Grab the field list from the meta class
+        fields = obj._meta._fields()
+
+        for field in fields:
+            # Decode and strip any html out of the field's help text
+            help_text = strip_tags(force_unicode(field.help_text))
+
+            # Decode and capitalize the verbose name, for use if there isn't
+            # any help text
+            verbose_name = force_unicode(field.verbose_name).capitalize()
+
+            if help_text:
+                # Add the model field to the end of the docstring as a param
+                # using the help text as the description
+                lines.append(u':param %s: %s' % (field.attname, help_text))
+            else:
+                # Add the model field to the end of the docstring as a param
+                # using the verbose name as the description
+                lines.append(u':param %s: %s' % (field.attname, verbose_name))
+
+            # Add the field's type to the docstring
+            lines.append(u':type %s: %s' % (field.attname, type(field).__name__))
+    return lines
+
+
+def setup(app):
+    """Setup docsting processors"""
+    #Register the docstring processor with sphinx
+    app.connect('autodoc-process-docstring', process_docstring)

docs/en_us/platform_api/source/course_info.rst

+##################################################
+Course Information API Module
+##################################################
+
+.. module:: mobile_api
+
+This page contains docstrings and example responses for:
+
+* `Get Course Updates`_
+* `Get Course Handouts`_
+* `Get the Course About Page`_
+  
+
+.. _Get Course Updates:
+
+*******************
+Get Course Updates
+*******************
+
+.. .. autoclass:: course_info.views.CourseUpdatesList
+
+**Use Case**
+
+Get the content for course updates.
+
+**Example request**:
+
+``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates``
+
+**Response Values**
+
+A array of course updates. Each course update contains:
+
+* date: The date of the course update.
+
+* content: The content, as a string, of the course update. HTML tags are not
+  included in the string.
+
+* status: Whether the update is visible or not.
+
+* id: The unique identifier of the update.
+
+**Example response**
+
+.. code-block:: json
+
+    HTTP 200 OK
+    Content-Type: application/json
+    Vary: Accept
+    Allow: GET, HEAD, OPTIONS
+
+    [
+        {
+            "date": "October 4, 2014", 
+            "content": "Reminder about the quiz due today. 
+            "status": "visible", 
+            "id": 2
+        }, 
+ 
+        { "date": "October 1, 2014", 
+          "content": "Welcome to the course. We
+            built this to help you become more familiar with taking a course on
+            edX prior to your first day of class. \n<br>\n<br>\nIn a live course,
+            this section is where all of the latest course announcements and
+            updates would be., 
+            "id": 1 } ]
+
+.. _Get Course Handouts:
+
+*******************
+Get Course Handouts
+*******************
+
+.. .. autoclass:: course_info.views.CourseHandoutsList
+
+**Use Case**
+
+Get the HTML for course handouts.
+
+**Example request**:
+
+``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts``
+
+**Response Values**
+
+* handouts_html: The HTML for course handouts.
+
+**Example response**
+
+.. code-block:: json
+
+    HTTP 200 OK
+    Content-Type: application/json
+    Vary: Accept
+    Allow: GET, HEAD, OPTIONS
+
+    {
+        "handouts_html": "\n\n<ol class=\"treeview-handoutsnav\">\n
+                          <li><a href=\"/static/demoPDF.pdf\">Example handout</a></li> 
+                          </ol>\n\n"
+    }
+
+
+.. _Get the Course About Page:
+
+**************************
+Get the Course About Page
+**************************
+
+.. .. autoclass:: course_info.views.CourseAboutDetail
+..    :members:
+
+**Use Case**
+
+Get the HTML for the course about page.
+
+**Example request**:
+
+``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about``
+
+**Response Values**
+
+* overview: The HTML for the course About page.
+
+**Example response**
+
+.. code-block:: json
+
+    HTTP 200 OK
+    Content-Type: application/json
+    Vary: Accept
+    Allow: GET, HEAD, OPTIONS
+
+    {
+        "overview": "<section class=\"about\">\n
+                     <h2>About This Course</h2>\n   
+                     <p>Include your long course description here. The long course description should contain 150-400 words.</p>
+                     <p>This is paragraph 2 of the long course description. Add more paragraphs as needed. Make sure to enclose them in paragraph tags.</p>
+                     </section>\n\n 
+                     <section class=\"prerequisites\">\n   
+                     <h2>Prerequisites</h2>\n   
+                     <p>Add information about course prerequisites here.</p>\n </section>\n\n 
+                     <section class=\"course-staff\">\n   
+                     <h2>Course Staff</h2>\n   
+                     <article class=\"teacher\">\n     
+                     <div class=\"teacher-image\">\n       
+                     <img src=\"/static/images/pl-faculty.png\" align=\"left\" style=\"margin:0 20 px 0\">\n     
+                     </div>\n\n     
+                     <h3>Staff Member #1</h3>\n     
+                     <p>Biography of instructor/staff member #1</p>\n   
+                     </article>\n\n   
+                     <article class=\"teacher\">\n     
+                     <div class=\"teacher-image\">\n       
+                     <img src=\"/static/images/pl-faculty.png\" align=\"left\" style=\"margin:0 20 px 0\">\n     
+                     </div>\n\n     
+                     <h3>Staff Member #2</h3>\n     
+                     <p>Biography of instructor/staff member #2</p>\n   
+                     </article>\n 
+                     </section>\n\n 
+                     <section class=\"faq\">\n   
+                     <section class=\"responses\">\n     
+                     <h2>Frequently Asked Questions</h2>\n     
+                     <article class=\"response\">\n       
+                     <h3>Do I need to buy a textbook?</h3>\n       
+                     <p>No, a free online version of Chemistry: Principles, Patterns, and Applications, First Edition by Bruce Averill and Patricia Eldredge will be available, though you can purchase a printed version (published by FlatWorld Knowledge) if you\u2019d like.</p>\n     
+                     </article>\n\n     
+                     <article class=\"response\">\n       
+                     <h3>Question #2</h3>\n       
+                     <p>Your answer would be displayed here.</p>\n     
+                     </article>\n   
+                     </section>\n 
+                     </section>"
+    }

docs/en_us/platform_api/source/endpoints.rst

+.. _edX Platform API Endpoints:
+
+################################################
+edX LMS Platform Endpoints
+################################################
+
+The edX Platform API allows you to view information about users and their course enrollments, course information, and videos and transcripts.
+
+The following tasks and endpoints are currently supported. 
+
+
+.. list-table::
+   :widths: 10 70
+   :header-rows: 1
+
+   * - To:
+     - Use this endpoint:
+   * - :ref:`Get details about a user<Get User Details>`
+     - /api/mobile/v0.5/users/{username}
+   * - :ref:`Get course enrollments for about a user<Get a User's Course Enrollments>`
+     - /api/mobile/v0.5/users/{username}/course_enrollments/
+   * - :ref:`Get a course About page<Get the Course About Page>`
+     - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about
+   * - :ref:`Get updates for a course<Get Course Updates>`
+     - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates   
+   * - :ref:`Get handouts for a course<Get Course Handouts>`
+     - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
+   * - :ref:`Get videos in a course<Get the Video List>`
+     - /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
+   * - :ref:`Get a video transcript<Get a Video Transcript>`
+     - /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

docs/en_us/platform_api/source/index.rst

+################################################
+edX Platform API Version 0.5
+################################################
+
+.. toctree::
+    :maxdepth: 2
+    
+    read_me
+    preface
+    overview
+    authentication
+    endpoints
+    users
+    course_info
+    video_outlines

docs/en_us/platform_api/source/links.rst

+.. _OAuth 2.0 Standard: https://tools.ietf.org/html/draft-ietf-oauth-v2-31
\ No newline at end of file

docs/en_us/platform_api/source/overview.rst

+.. _edX Platform API Overview:
+
+################################################
+edX Platform API Overview
+################################################
+
+The edX Platform API enables you to build applications for students to view
+course information and videos for courses on your instance of Open edX.
+
+The edX Platform API uses Representational State Transfer (REST) design
+principles and supports JavaScript Object Notation (JSON) data-interchange
+format. Our REST API is simple, lightweight and optimized.
+
+You can use the edX Platform API for web, desktop, and mobile applications. 
+
+
+*************************************
+edX Platform API Version 0.5, Alpha
+*************************************
+
+The edX Platform API is currently at version 0.5 and is an Alpha release. We
+plan on making significant enhancements and changes to the API. 
+
+.. caution::
+ As this is a new and rapidly evolving API, at this time edX does not guarantee
+ forward compatibility. We encourage you to use and experiment with the API,
+ while keeping in mind that endpoints may change.
+
+******************************
+edX Platform API Capabilities
+******************************
+
+With the edX Platform API, you can:
+
+* Get :ref:`user details<Get User Details>` and :ref:`course enrollments<Get a
+  User's Course Enrollments>` for a user.
+
+* Get :ref:`course information<Get the Course About Page>`, :ref:`updates<Get
+  Course Updates>`, and :ref:`handouts<Get Course Handouts>` for courses the
+  user is enrolled in.
+
+* Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video
+  Transcript>` for courses the user is enrolled in.
\ No newline at end of file

docs/en_us/platform_api/source/preface.rst

+.. include:: ../../shared/preface.rst
\ No newline at end of file

docs/en_us/platform_api/source/read_me.rst

+########
+Read Me
+########
+
+The edX Platform API documentation is created using RST_
+files and Sphinx_. You, the user community, can help update and revise this
+documentation project on GitHub:
+
+  https://github.com/edx/edx-platform/tree/master/docs/platforms_api/source
+
+To suggest a revision, fork the project, make changes in your fork, and submit
+a pull request back to the original project: this is known as the `GitHub Flow`_.
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _LaTeX: http://www.latex-project.org/
+.. _`GitHub Flow`: https://github.com/blog/1557-github-flow-in-the-browser
+.. _RST: http://docutils.sourceforge.net/rst.html
\ No newline at end of file

docs/en_us/platform_api/source/users.rst

+#########################
+User API Module
+#########################
+
+.. module:: mobile_api
+
+This page describes how to use the mobile user API to:
+
+* `Get User Details`_
+* `Get a User's Course Enrollments`_
+
+.. _Get User Details:
+
+*******************
+Get User Details
+*******************
+
+.. .. autoclass:: mobile_api.users.views.UserDetail
+..    :members:
+
+**Use Case**
+
+Get information about the specified user and access other resources the user
+has permissions for.
+
+Users are redirected to this endpoint after logging in.
+
+You can use the **course_enrollments** value in the response to get a list of
+courses the user is enrolled in.
+
+**Example request**:
+
+``GET /api/mobile/v0.5/users/{username}``
+
+**Response Values**
+
+* id: The ID of the user.
+
+* username: The username of the currently logged in user.
+
+* email: The email address of the currently logged in user.
+
+* name: The full name of the currently logged in user.
+
+* course_enrollments: The URI to list the courses the currently logged in user
+  is enrolled in.
+
+**Example response**
+
+.. code-block:: json
+
+    HTTP 200 OK  
+    Vary: Accept   
+    Content-Type: text/html; charset=utf-8   
+    Allow: GET, HEAD, OPTIONS 
+
+    {
+        "id": 67, 
+        "username": "mtwain", 
+        "email": "mtwain@email-domain.com", 
+        "name": "mtwain", 
+        "course_enrollments": "http://localhost:8000/api/mobile/v0.5/users/mtwain/course_enrollments/"
+    }
+
+.. _Get a User's Course Enrollments:
+
+**************************************
+Get a User's Course Enrollments
+**************************************
+
+.. .. autoclass:: users.views.UserCourseEnrollmentsList
+..    :members:
+
+**Use Case**
+
+Get information about the courses the currently logged in user is enrolled in.
+
+**Example request**:
+
+``GET /api/mobile/v0.5/users/{username}/course_enrollments/``
+
+**Response Values**
+
+* created: The date the course was created.
+        
+* mode: The type of certificate registration for this course:  honor or
+  certified.
+        
+* is_active: Whether the course is currently active; true or false.
+    
+* course: A collection of data about the course:
+        
+* course_about: The URI to get the data for the course About page.
+          
+* course_updates: The URI to get data for course updates.
+          
+* number: The course number.
+          
+* org: The organization that created the course.
+          
+* video_outline: The URI to get the list of all vides the user can access in
+  the course.
+          
+* id: The unique ID of the course.
+          
+* latest_updates:  Reserved for future use.
+          
+* end: The end date of the course.
+          
+* name: The name of the course.
+          
+* course_handouts: The URI to get data for course handouts.
+          
+* start: The data and time the course starts.
+          
+* course_image: The path to the course image.
+
+**Example response**
+
+.. code-block:: json
+
+    HTTP 200 OK  
+    Vary: Accept   
+    Content-Type: text/html; charset=utf-8   
+    Allow: GET, HEAD, OPTIONS 
+
+    {
+        "created": "2014-04-18T13:44:25Z", 
+        "mode": "honor", 
+        "is_active": true, 
+        "course": {
+            "course_about": "http://localhost:8000/api/mobile/v0.5/course_info/edX/Open_DemoX/edx_demo_course/about", 
+            "course_updates": "http://localhost:8000/api/mobile/v0.5/course_info/edX/Open_DemoX/edx_demo_course/updates", 
+            "number": "Open_DemoX", 
+            "org": "edX", 
+            "video_outline": "http://localhost:8000/api/mobile/v0.5/video_outlines/courses/edX/Open_DemoX/edx_demo_course", 
+            "id": "edX/Open_DemoX/edx_demo_course", 
+            "latest_updates": {
+                "video": null
+            }, 
+            "end": null, 
+            "name": "edX Demonstration Course", 
+            "course_handouts": "http://localhost:8000/api/mobile/v0.5/course_info/edX/Open_DemoX/edx_demo_course/handouts", 
+            "start": "1970-01-01T05:00:00Z", 
+            "course_image": "/c4x/edX/Open_DemoX/asset/images_course_image.jpg"
+        }
+    }, 
+    {
+        "created": "2014-09-29T13:46:06Z", 
+        "mode": "honor", 
+        "is_active": true, 
+        "course": {
+            "course_about": "http://localhost:8000/api/mobile/v0.5/course_info/edX/DemoX/Demo_Course/about", 
+            "course_updates": "http://localhost:8000/api/mobile/v0.5/course_info/edX/DemoX/Demo_Course/updates", 
+            "number": "DemoX", 
+            "org": "edX", 
+            "video_outline": "http://localhost:8000/api/mobile/v0.5/video_outlines/courses/edX/DemoX/Demo_Course", 
+            "id": "edX/DemoX/Demo_Course", 
+            "latest_updates": {
+                "video": null
+            }, 
+            "end": null, 
+            "name": "edX Demonstration Course", 
+            "course_handouts": "http://localhost:8000/api/mobile/v0.5/course_info/edX/DemoX/Demo_Course/handouts", 
+            "start": "2013-02-05T05:00:00Z", 
+            "course_image": "/c4x/edX/DemoX/asset/images_course_image.jpg"
+        }
+    }
\ No newline at end of file

docs/en_us/platform_api/source/video_outlines.rst

+##################################################
+Video Outlines API Module
+##################################################
+
+.. module:: mobile_api
+
+This page contains docstrings and example responses for:
+
+* `Get the Video List`_
+* `Get a Video Transcript`_
+
+.. _Get the Video List:
+
+*******************
+Get the Video List
+*******************
+
+.. .. autoclass:: video_outlines.views.VideoSummaryList
+..    :members:
+
+**Use Case**
+
+Get a list of all videos in the specified course. You can use the video_url
+value to access the video file.
+
+**Example request**:
+
+``GET /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}``
+
+**Response Values**
+
+An array of videos in the course. For each video:
+
+* section_url: The URL to the first page of the section that contains the video
+  in the Learning Managent System.
+
+* path: An array containing category and name values specifying the complete
+  path the the video in the courseware hierarcy. The following categories
+  values are included: "chapter", "sequential", and "vertical". The name value
+  is the display name for that object.
+
+* unit_url: The URL to the unit contains the video in the Learning Managent
+  System.
+
+* named_path: An array consisting of the display names of the courseware
+  objects in the path to the video.
+
+* summary:  An array of data about the video that includes:
+
+    * category:  The type of component, in this case always "video".
+
+    * video_thumbnail_url: The URL to the thumbnail image for the video, if
+      available.
+
+    * language: The language code for the video.
+
+    * name:  The display name of the video.
+
+    * video_url: The URL to the video file. Use this value to access the video.
+
+    * duration: The length of the video, if available.
+
+    * transcripts: An array of language codes and URLs to available video
+      transcripts. Use the URL value to access a transcript for the video.
+
+    * id: The unique identifier for the video.
+
+    * size: The size of the video file
+
+**Example response**
+
+.. code-block:: json
+
+    HTTP 200 OK  
+    Vary: Accept   
+    Content-Type: text/html; charset=utf-8   
+    Allow: GET, HEAD, OPTIONS 
+
+    [
+        {
+            "section_url": "http://localhost:8000/courses/edX/Open_DemoX/edx_demo_course/courseware/d8a6192ade314473a78242dfeedfbf5b/edx_introduction/", 
+            "path": [
+                {
+                    "category": "chapter", 
+                    "name": "Introduction"
+                }, 
+                {
+                    "category": "sequential", 
+                    "name": "Demo Course Overview"
+                }, 
+                {
+                    "category": "vertical", 
+                    "name": "Introduction: Video and Sequences"
+                }
+            ], 
+            "unit_url": "http://localhost:8000/courses/edX/Open_DemoX/edx_demo_course/courseware/d8a6192ade314473a78242dfeedfbf5b/edx_introduction/1", 
+            "named_path": [
+                "Introduction", 
+                "Demo Course Overview"
+            ], 
+            "summary": {
+                "category": "video", 
+                "video_thumbnail_url": null, 
+                "language": "en", 
+                "name": "Welcome!", 
+                "video_url": "https://s3.amazonaws.com/edx-course-videos/edx-edx101/EDXSPCPJSP13-H010000_100.mp4", 
+                "duration": null, 
+                "transcripts": {
+                    "en": "http://localhost:8000/api/mobile/v0.5/video_outlines/transcripts/edX/Open_DemoX/edx_demo_course/0b9e39477cf34507a7a48f74be381fdd/en"
+                }, 
+                "id": "i4x://edX/Open_DemoX/video/0b9e39477cf34507a7a48f74be381fdd", 
+                "size": 0
+            }
+        }
+    ] 
+
+.. _Get a Video Transcript:
+
+***********************
+Get a Video Transcript
+***********************
+
+.. .. autoclass:: video_outlines.views.VideoTranscripts
+..    :members:
+
+**Use Case**
+
+Use to get a transcript for a specified video and language.
+
+**Example request**:
+
+``/api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}``
+    
+**Response Values**
+
+An HttpResponse with an SRT file download.
\ No newline at end of file

lms/djangoapps/mobile_api/course_info/views.py

@@ -13,10 +13,27 @@ from xmodule.modulestore.django import modulestore
 
 
 class CourseUpdatesList(generics.ListAPIView):
-    """Notes:
+    """
+    **Use Case**
+
+        Get the content for course updates.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
+
+    **Response Values**
 
-    1. This only works for new-style course updates and is not the older freeform
-       format.
+        A array of course updates. Each course update contains:
+
+            * date: The date of the course update.
+
+            * content: The content, as a string, of the course update. HTML tags
+              are not included in the string.
+
+            * status: Whether the update is visible or not.
+
+            * id: The unique identifier of the update.
     """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated,)
@@ -33,7 +50,18 @@ class CourseUpdatesList(generics.ListAPIView):
 
 
 class CourseHandoutsList(generics.ListAPIView):
-    """Please just render this in an HTML view for now.
+    """
+    **Use Case**
+
+        Get the HTML for course handouts.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
+
+    **Response Values**
+
+        * handouts_html: The HTML for course handouts.
     """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated,)
@@ -52,7 +80,17 @@ class CourseHandoutsList(generics.ListAPIView):
 
 class CourseAboutDetail(generics.RetrieveAPIView):
     """
-    Renders course 'about' page
+    **Use Case**
+
+        Get the HTML for the course about page.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about
+
+    **Response Values**
+
+        * overview: The HTML for the course About page.
     """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated,)

lms/djangoapps/mobile_api/users/views.py

@@ -23,10 +23,33 @@ class IsUser(permissions.BasePermission):
 
 
 class UserDetail(generics.RetrieveAPIView):
-    """Read-only information about our User.
+    """
+    **Use Case**
+
+        Get information about the specified user and
+        access other resources the user has permissions for.
+
+        Users are redirected to this endpoint after logging in.
+
+        You can use the **course_enrollments** value in
+        the response to get a list of courses the user is enrolled in.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/users/{username}
+
+    **Response Values**
+
+        * id: The ID of the user.
+
+        * username: The username of the currently logged in user.
+
+        * email: The email address of the currently logged in user.
 
-    This will be where users are redirected to after API login and will serve
-    as a place to list all useful resources this user can access.
+        * name: The full name of the currently logged in user.
+
+        * course_enrollments: The URI to list the courses the currently logged
+          in user is enrolled in.
     """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated, IsUser)
@@ -39,7 +62,38 @@ class UserDetail(generics.RetrieveAPIView):
 
 
 class UserCourseEnrollmentsList(generics.ListAPIView):
-    """Read-only list of courses that this user is enrolled in."""
+    """
+    **Use Case**
+
+        Get information about the courses the currently logged in user is
+        enrolled in.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/users/{username}/course_enrollments/
+
+    **Response Values**
+
+        * created: The date the course was created.
+        * mode: The type of certificate registration for this course:  honor or
+          certified.
+        * is_active: Whether the course is currently active; true or false.
+        * course: A collection of data about the course:
+        
+          * course_about: The URI to get the data for the course About page.
+          * course_updates: The URI to get data for course updates.
+          * number: The course number.
+          * org: The organization that created the course.
+          * video_outline: The URI to get the list of all vides the user can
+            access in the course.
+          * id: The unique ID of the course.
+          * latest_updates:  Reserved for future use.
+          * end: The end date of the course.
+          * name: The name of the course.
+          * course_handouts: The URI to get data for course handouts.
+          * start: The data and time the course starts.
+          * course_image: The path to the course image.
+    """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated, IsUser)
     queryset = CourseEnrollment.objects.all()

lms/djangoapps/mobile_api/video_outlines/views.py

@@ -25,7 +25,58 @@ from .serializers import BlockOutline, video_summary
 
 
 class VideoSummaryList(generics.ListAPIView):
-    """A list of all Videos in this Course that the user has access to."""
+    """
+    **Use Case**
+
+        Get a list of all videos in the specified course. You can use the
+        video_url value to access the video file.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
+
+    **Response Values**
+
+        An array of videos in the course. For each video:
+
+            * section_url: The URL to the first page of the section that
+              contains the video in the Learning Managent System.
+
+            * path: An array containing category and name values specifying the
+              complete path the the video in the courseware hierarcy. The
+              following categories values are included: "chapter", "sequential",
+              and "vertical". The name value is the display name for that object.
+
+            * unit_url: The URL to the unit contains the video in the Learning
+              Managent System.
+
+            * named_path: An array consisting of the display names of the
+              courseware objects in the path to the video.
+
+            * summary:  An array of data about the video that includes:
+
+                * category:  The type of component, in this case always "video".
+
+                * video_thumbnail_url: The URL to the thumbnail image for the
+                  video, if available.
+
+                * language: The language code for the video.
+
+                * name:  The display name of the video.
+
+                * video_url: The URL to the video file. Use this value to access
+                  the video.
+
+                * duration: The length of the video, if available.
+
+                * transcripts: An array of language codes and URLs to available
+                  video transcripts. Use the URL value to access a transcript
+                  for the video.
+
+                * id: The unique identifier for the video.
+
+                * size: The size of the video file
+    """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated,)
 
@@ -45,9 +96,19 @@ class VideoSummaryList(generics.ListAPIView):
 
 
 class VideoTranscripts(generics.RetrieveAPIView):
-    """Read-only view for a single transcript (SRT) file for a particular language.
+    """
+    **Use Case**
+
+        Use to get a transcript for a specified video and language.
+
+    **Example request**:
+
+        GET /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}
+    
+    **Response Values**
+
+        An HttpResponse with an SRT file download.
 
-    Returns an `HttpResponse` with an SRT file download for the body.
     """
     authentication_classes = (OAuth2Authentication, SessionAuthentication)
     permission_classes = (permissions.IsAuthenticated,)