From d33f23764449d9568e0e5e48ea366f5e1701f38e Mon Sep 17 00:00:00 2001 From: Mark Hoeber Date: Thu, 10 Sep 2015 15:55:17 -0400 Subject: [PATCH] Fix and cleanup of API doc --- docs/en_us/platform_api/source/conf.py | 24 ++++++++++++++++--- .../course_structure/course_structure.rst | 20 +++++++--------- .../source/course_structure/overview.rst | 4 ++++ .../platform_api/source/docs_settings.py | 8 +++++++ .../source/enrollment/enrollment.rst | 13 ++++------ .../source/enrollment/overview.rst | 5 ++-- .../source/mobile/course_info.rst | 5 ++-- .../platform_api/source/mobile/overview.rst | 4 ++++ .../platform_api/source/mobile/users.rst | 7 +++--- .../source/mobile/video_outlines.rst | 7 +++--- .../source/profile_images/overview.rst | 4 ++++ .../source/profile_images/profile_images.rst | 5 ++-- .../platform_api/source/user/accounts.rst | 4 +++- .../platform_api/source/user/overview.rst | 4 +++- .../platform_api/source/user/preferences.rst | 5 ++-- 15 files changed, 79 insertions(+), 40 deletions(-) create mode 100644 docs/en_us/platform_api/source/docs_settings.py diff --git a/docs/en_us/platform_api/source/conf.py b/docs/en_us/platform_api/source/conf.py index d929c6a560..1e7a4450f6 100644 --- a/docs/en_us/platform_api/source/conf.py +++ b/docs/en_us/platform_api/source/conf.py @@ -189,17 +189,34 @@ MOCK_MODULES = [ 'ecommerce_api_client', 'client', 'ecommerce_api_client.client', - 'ecommerce_api_client.exceptions' - - + 'ecommerce_api_client.exceptions', + 'student.auth', + 'ccx_keys', + 'ccx_keys.locator', + 'user_api.preferences.api' ] for mod_name in MOCK_MODULES: sys.modules[mod_name] = mock.Mock(class_that_is_extended=object) +if "DJANGO_SETTINGS_MODULE" not in os.environ: + docs_path = os.getcwd() + mezzanine_path_parts = (docs_path, "..") + sys.path.insert(0, docs_path) + sys.path.insert(0, os.path.realpath(os.path.join(*mezzanine_path_parts))) + os.environ["DJANGO_SETTINGS_MODULE"] = "docs_settings" + # Django 1.7's setup is required before touching translated strings. + import django + try: + django.setup() + except AttributeError: # < 1.7 + pass + on_rtd = os.environ.get('READTHEDOCS', None) == 'True' sys.path.append('../../../../') +os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.dev' +#os.environ.setdefault("DJANGO_SETTINGS_MODULE", "lms.envs.dev") from docs.shared.conf import * @@ -227,6 +244,7 @@ sys.path.insert(0, root) sys.path.append(root / "common/lib/xmodule") sys.path.append(root / "common/djangoapps") sys.path.append(root / "lms/djangoapps") +sys.path.append(root / "lms/envs") sys.path.append(root / "openedx/core/djangoapps") sys.path.insert( diff --git a/docs/en_us/platform_api/source/course_structure/course_structure.rst b/docs/en_us/platform_api/source/course_structure/course_structure.rst index 83724eed63..7becd812c2 100644 --- a/docs/en_us/platform_api/source/course_structure/course_structure.rst +++ b/docs/en_us/platform_api/source/course_structure/course_structure.rst @@ -1,17 +1,13 @@ ######################################## -Course Structure API +Course Structure API Resource ######################################## -This page contains information on using the Course Structure API to -complete the following actions. +With the Course Structure API **Course Structure** resource, you can complete +the following tasks. -* :ref:`Get a list of courses in the edX platform ` - -* :ref:`Get details about a course ` - -* :ref:`Get a course's structure, or blocks ` - -* :ref:`Get a courses grading policy ` +.. contents:: + :local: + :depth: 1 .. _Get a List of Courses: @@ -58,6 +54,8 @@ Get a List of Courses . . . ] } + + .. _Get Course Details: ************************** @@ -94,7 +92,7 @@ Get Course Details Get the Course Structure ************************** -.. autoclass:: course_structure_api.v0.views.CourseStructure +.. .. autoclass:: course_structure_api.v0.views.CourseStructure **Example response** diff --git a/docs/en_us/platform_api/source/course_structure/overview.rst b/docs/en_us/platform_api/source/course_structure/overview.rst index ab8e5b7fdc..72513f8cfb 100644 --- a/docs/en_us/platform_api/source/course_structure/overview.rst +++ b/docs/en_us/platform_api/source/course_structure/overview.rst @@ -7,6 +7,10 @@ Course Structure API Overview Use the edX Platform Course Structure API to view course details, including the blocks in the course and the course grading policy. +.. contents:: + :local: + :depth: 1 + ******************************************** Course Structure API Version 0 ******************************************** diff --git a/docs/en_us/platform_api/source/docs_settings.py b/docs/en_us/platform_api/source/docs_settings.py new file mode 100644 index 0000000000..47c1f0e1c9 --- /dev/null +++ b/docs/en_us/platform_api/source/docs_settings.py @@ -0,0 +1,8 @@ +""" +This is the local_settings file for platform API doc. +""" + +# Generate a SECRET_KEY for this build +from random import choice +characters = 'abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)' +SECRET_KEY = ''.join([choice(characters) for i in range(50)]) diff --git a/docs/en_us/platform_api/source/enrollment/enrollment.rst b/docs/en_us/platform_api/source/enrollment/enrollment.rst index 97395ffe9d..2630b77004 100644 --- a/docs/en_us/platform_api/source/enrollment/enrollment.rst +++ b/docs/en_us/platform_api/source/enrollment/enrollment.rst @@ -5,14 +5,9 @@ Enrollment API Enrollment Resource With the Enrollment API **Enrollment** resource, you can complete the following tasks. -* :ref:`Get the user's enrollment status in a course `. -* :ref:`Get the user's enrollment information for a course`. -* :ref:`View a user's enrollments `. -* :ref:`Enroll a user in a course `. +.. contents:: + :local: + :depth: 1 .. _Get the Users Enrollment Status in a Course: @@ -62,7 +57,7 @@ Get the User's Enrollment Status in a Course Get the User's Enrollment Information for a Course ************************************************** -.. autoclass:: enrollment.views.EnrollmentCourseDetailView +.. .. autoclass:: enrollment.views.EnrollmentCourseDetailView **Example response showing a user's course enrollment information** diff --git a/docs/en_us/platform_api/source/enrollment/overview.rst b/docs/en_us/platform_api/source/enrollment/overview.rst index 7e219dee20..010c9a36fc 100644 --- a/docs/en_us/platform_api/source/enrollment/overview.rst +++ b/docs/en_us/platform_api/source/enrollment/overview.rst @@ -7,8 +7,9 @@ Enrollment API Overview Use the Enrollment API to view user and course enrollment information and to enroll a user in a course. -You can use the Enrollment API for web, desktop, and mobile -applications. +.. contents:: + :local: + :depth: 1 **************************************** Enrollment API Version and Status diff --git a/docs/en_us/platform_api/source/mobile/course_info.rst b/docs/en_us/platform_api/source/mobile/course_info.rst index 47c3fca90e..a4c436b377 100644 --- a/docs/en_us/platform_api/source/mobile/course_info.rst +++ b/docs/en_us/platform_api/source/mobile/course_info.rst @@ -5,8 +5,9 @@ Mobile API Course Information Resource With the Mobile API **Course Information** resource, you can complete the following tasks. -* :ref:`Get updates about a course`. -* :ref:`Get a list of course handouts`. +.. contents:: + :local: + :depth: 1 .. _Get Course Updates: diff --git a/docs/en_us/platform_api/source/mobile/overview.rst b/docs/en_us/platform_api/source/mobile/overview.rst index 0d3da876b8..11b40d7367 100644 --- a/docs/en_us/platform_api/source/mobile/overview.rst +++ b/docs/en_us/platform_api/source/mobile/overview.rst @@ -7,6 +7,10 @@ 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. +.. contents:: + :local: + :depth: 1 + ****************************************** Mobile API Version and Status ****************************************** diff --git a/docs/en_us/platform_api/source/mobile/users.rst b/docs/en_us/platform_api/source/mobile/users.rst index c56e3af7db..8159ef3fc0 100644 --- a/docs/en_us/platform_api/source/mobile/users.rst +++ b/docs/en_us/platform_api/source/mobile/users.rst @@ -4,10 +4,9 @@ Mobile API User Resource With the Mobile API **User** resource, you can complete the following tasks. -* :ref:`Get details about a user`. -* :ref:`Get course enrollments for a user`. -* :ref:`Get a user's status in a course`. -* :ref:`Change a user's status in a course`. +.. contents:: + :local: + :depth: 1 .. _Get User Details: diff --git a/docs/en_us/platform_api/source/mobile/video_outlines.rst b/docs/en_us/platform_api/source/mobile/video_outlines.rst index 45fb4e7183..2fb41ac0cd 100644 --- a/docs/en_us/platform_api/source/mobile/video_outlines.rst +++ b/docs/en_us/platform_api/source/mobile/video_outlines.rst @@ -5,8 +5,9 @@ Mobile API Video Outlines Resource With the Mobile API **Video Outlines** resource, you can complete the following tasks. -* :ref:`Get a list of all videos in the course `. -* :ref:`Get a transcript for a specified video and language `. +.. contents:: + :local: + :depth: 1 .. _Get the Video List: @@ -70,4 +71,4 @@ Get the Course Video List Get a Video Transcript *********************** -.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts \ No newline at end of file +.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts diff --git a/docs/en_us/platform_api/source/profile_images/overview.rst b/docs/en_us/platform_api/source/profile_images/overview.rst index f9a5efcc87..8938e1dbe7 100644 --- a/docs/en_us/platform_api/source/profile_images/overview.rst +++ b/docs/en_us/platform_api/source/profile_images/overview.rst @@ -8,6 +8,10 @@ The requesting user can upload or remove his or her own profile image. Users with staff access can remove profile images from any user account. +.. contents:: + :local: + :depth: 1 + ************************************* Profile Images API Version and Status ************************************* diff --git a/docs/en_us/platform_api/source/profile_images/profile_images.rst b/docs/en_us/platform_api/source/profile_images/profile_images.rst index 02365ac0d7..3d692a041f 100644 --- a/docs/en_us/platform_api/source/profile_images/profile_images.rst +++ b/docs/en_us/platform_api/source/profile_images/profile_images.rst @@ -7,8 +7,9 @@ Profile Images API Profile Images Resource With the Profile Images API **Profile Images** resource, you can complete the following tasks. -* :ref:`Upload a profile image `. -* :ref:`Remove profile images `. +.. contents:: + :local: + :depth: 1 .. _Upload a Profile Image: diff --git a/docs/en_us/platform_api/source/user/accounts.rst b/docs/en_us/platform_api/source/user/accounts.rst index ec02f93ca0..c8cb29a8d0 100644 --- a/docs/en_us/platform_api/source/user/accounts.rst +++ b/docs/en_us/platform_api/source/user/accounts.rst @@ -7,7 +7,9 @@ User API User Accounts Resource With the User API **User Accounts** resource, you can complete the following tasks. -* `Get and Update the User's Account Information`_ +.. contents:: + :local: + :depth: 1 .. _Get and Update the User's Account Information: diff --git a/docs/en_us/platform_api/source/user/overview.rst b/docs/en_us/platform_api/source/user/overview.rst index 7dc96ca262..ad2ac80aaf 100644 --- a/docs/en_us/platform_api/source/user/overview.rst +++ b/docs/en_us/platform_api/source/user/overview.rst @@ -4,7 +4,9 @@ User API Overview Use the User API to view and update account and preference information. -You can use the User API for web, desktop, and mobile applications. +.. contents:: + :local: + :depth: 1 ************************************* User API Version and Status diff --git a/docs/en_us/platform_api/source/user/preferences.rst b/docs/en_us/platform_api/source/user/preferences.rst index c786c8b9ed..b05757e72c 100644 --- a/docs/en_us/platform_api/source/user/preferences.rst +++ b/docs/en_us/platform_api/source/user/preferences.rst @@ -7,8 +7,9 @@ User API User Preferences Resource 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`_ +.. contents:: + :local: + :depth: 1 .. _Get and Update the User's Preferences Information: