Final tweaks to API documentation updates

common/djangoapps/enrollment/views.py

@@ -319,17 +319,16 @@ class EnrollmentListView(APIView, ApiKeyPermissionMixIn):
 
               A POST request can include the following parameters.
 
-              * user: The username of the currently logged in user. Optional.
+              * user: Optional. The username of the currently logged in user.
                 You cannot use the command to enroll a different user.
 
-              * mode: The course mode for the enrollment. Individual users
-                cannot upgrade their enrollment mode from 'honor'. Only
+              * mode: Optional. The course mode for the enrollment. Individual
+                users cannot upgrade their enrollment mode from 'honor'. Only
                 server-to-server requests can enroll with other modes.
-                Optional.
 
-              * is_active: A Boolean value indicating whether the enrollment
-                is active. Only server-to-server requests are allowed to
-                deactivate an enrollment. Optional.
+              * is_active: Optional. A Boolean value indicating whether the
+                enrollment is active. Only server-to-server requests are
+                allowed to deactivate an enrollment.
 
               * course details: A collection that includes the following
                 information.
@@ -340,7 +339,8 @@ class EnrollmentListView(APIView, ApiKeyPermissionMixIn):
                 the user wants to receive email from the organization that runs
                 this course.
 
-              * enrollment_attributes: A list of dictionary that contains:
+              * enrollment_attributes: A dictionary that contains the following
+                values.
 
                   * namespace: Namespace of the attribute
                   * name: Name of the attribute

docs/en_us/platform_api/source/enrollment/enrollment.rst

-##################################################
-Enrollment API 
-##################################################
+###################################
+Enrollment API Enrollment Resource 
+###################################
 
-You can use the Enrollment API to complete the following tasks.
+With the Enrollment API **Enrollment** resource, you can complete the
+following tasks.
 
 * :ref:`Get the user's enrollment status in a course <Get the Users Enrollment
   Status in a Course>`.
-* :ref:`Get enrollment details for a course<Get Enrollment Details for a
+* :ref:`Get the user's enrollment information for a course<Get Enrollment Details for a
   Course>`.
 * :ref:`View a user's enrollments <View and add to a Users Course
   Enrollments>`.
@@ -93,9 +94,9 @@ Get the User's Enrollment Information for a Course
 
 .. _View and add to a Users Course Enrollments:
 
-*********************************************
-View and Add to a User's Course Enrollments
-*********************************************
+**********************************************************
+View a User's Enrollments or Enroll a User in a Course
+**********************************************************
 
 .. autoclass:: enrollment.views.EnrollmentListView
 

docs/en_us/platform_api/source/enrollment/overview.rst

@@ -34,7 +34,7 @@ The Enrollment API supports the following tasks, methods, and endpoints.
        <Get the Users Enrollment Status in a Course>`
      - GET
      - /api/enrollment/v1/enrollment/{user_id},{course_id}
-   * - :ref:`Get enrollment details for a course
+   * - :ref:`Get the user's enrollment information for a course
        <Get Enrollment Details for a Course>`
      - GET
      - /api/enrollment/v1/course/{course_id}

docs/en_us/platform_api/source/mobile/course_info.rst

 ##################################################
-Mobile Course Information API Resource
+Mobile API Course Information Resource
 ##################################################
 
-With the Mobile Course Information API resource, you can complete the following tasks.
+With the Mobile API **Course Information** resource, you can complete the
+following tasks.
 
-* - :ref:`Get updates about a course<Get Course Updates>`.
-* - :ref:`Get a list of course handouts<Get Course Handouts>`.
+* :ref:`Get updates about a course<Get Course Updates>`.
+* :ref:`Get a list of course handouts<Get Course Handouts>`.
   
 .. _Get Course Updates:
 

docs/en_us/platform_api/source/mobile/index.rst

@@ -8,6 +8,6 @@ Mobile API Version 0.5
     :maxdepth: 2
     
     overview
-    users
     course_info
+    users
     video_outlines

docs/en_us/platform_api/source/mobile/overview.rst

@@ -4,29 +4,30 @@
 Mobile API Overview
 ################################################
 
-Use the Mobile API to build mobile applications for students to
-view course information and videos for courses on your instance of Open edX.
+Use the Mobile API to build mobile applications for students to view course
+information and videos for courses on your instance of Open edX.
 
 ******************************************
 Mobile API Version and Status
 ******************************************
 
-The Mobile API is currently at version 0.5 and is an Alpha
-release. We plan on making significant enhancements and changes to the API.
+The Mobile 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 might change.
+ 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 might change.
 
 *************************************
 Mobile API Resources and Endpoints
 *************************************
 
-The Mobile API supports the following resources, tasks, methods, and endpoints. 
+The Mobile API supports the following resources, tasks, methods, and
+endpoints.
 
 ========================
-Mobile User API Resource
+Mobile API User Resource
 ========================
 
 .. list-table::
@@ -50,7 +51,7 @@ Mobile User API Resource
      - /api/mobile/v0.5/rs/{username}/course_status_info/{course_id}
 
 ========================================
-Mobile Course Information API Resource
+Mobile API Course Information Resource
 ========================================
 
 .. list-table::
@@ -68,7 +69,7 @@ Mobile Course Information API Resource
      - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
 
 =====================================
-Mobile Video Outlines API Resource
+Mobile API Video Outlines Resource
 =====================================
 
 .. list-table::

docs/en_us/platform_api/source/mobile/users.rst

 ####################################
-Mobile User API
+Mobile API User Resource
 ####################################
 
-With the Mobile User API resource, you can complete the following tasks.
+With the Mobile API **User** resource, you can complete the following tasks.
 
-* - :ref:`Get details about a user<Get User Details>`.
-* - :ref:`Get course enrollments for a user<Get a User's Course Enrollments>`.
-* - :ref:`Get a user's status in a course<Get or Change User Status in a Course>`.
-* - :ref:`Change a user's status in a course<Get or Change User Status in a Course>`.
+* :ref:`Get details about a user<Get User Details>`.
+* :ref:`Get course enrollments for a user<Get a User's Course Enrollments>`.
+* :ref:`Get a user's status in a course<Get or Change User Status in a Course>`.
+* :ref:`Change a user's status in a course<Get or Change User Status in a Course>`.
 
 .. _Get User Details:
 

docs/en_us/platform_api/source/mobile/video_outlines.rst

 ##################################################
-Mobile Video Outlines API
+Mobile API Video Outlines Resource
 ##################################################
 
-This page describes how to use the Mobile Video Outlines API to
-complete these actions:
+With the Mobile API **Video Outlines** resource, you can complete the
+following tasks.
 
-* `Get the Video List`_
-* `Get a Video Transcript`_
+* :ref:`Get a list of all videos in the course <Get the Video List>`.
+* :ref:`Get a transcript for a specified video and language <Get a Video Transcript>`.
 
 .. _Get the Video List:
 
-*******************
-Get the Video List
-*******************
+**************************
+Get the Course Video List
+**************************
 
 .. autoclass:: mobile_api.video_outlines.views.VideoSummaryList
 

docs/en_us/platform_api/source/profile_images/profile_images.rst

 .. Profile Images API:
 
 ##################################################
-Profile Images API
+Profile Images API Profile Images Resource
 ##################################################
 
-You can use the Profile Images API to complete the following tasks.
+With the Profile Images API **Profile Images** resource, you can complete the
+following tasks.
 
-* - :ref:`Upload a profile image <Upload a Profile Image>`.
-* - :ref:`Remove profile images <Remove a Profile Image>`.
+* :ref:`Upload a profile image <Upload a Profile Image>`.
+* :ref:`Remove profile images <Remove a Profile Image>`.
 
 .. _Upload a Profile Image:
 

docs/en_us/platform_api/source/user/accounts.rst

 .. _User Accounts API:
 
 ##################################################
-User Accounts API
+User API User Accounts Resource
 ##################################################
 
-This page contains information on using the User Accounts API to
-complete the following actions.
+With the User API **User Accounts** resource, you can complete the following
+tasks.
 
 * `Get and Update the User's Account Information`_
 
@@ -31,7 +31,7 @@ Get and Update the User's Account Information
       "name": "John Doe", 
       "language": "", 
       "gender": "m", 
-      "year_of_birth": 1997, 
+      "year_of_birth": 1987, 
       "level_of_education": "m", 
       "goals": "Professional Development", 
       "country": US, 

docs/en_us/platform_api/source/user/preferences.rst

 .. _User Preferences API:
 
 ##################################################
-User Preferences API
+User API User Preferences Resource
 ##################################################
 
-This page contains information on using the User Preferences API to
-complete the following actions.
+With the User API **User Preferences** resource, you can complete the
+following tasks.
 
 * `Get and Update the User's Preferences Information`_
 * `Get, Update, or Delete a Specific Preference`_