Older REST API documentation projects used the Sphinx autodoc extension to include Python docstring content in RST-based documents. Using Sphinx autodoc requires the build process to import all the Python modules in the API implementation and makes publishing the documentation more complicated and prone to failure. This page holds information about setting up documentation using autodoc, in case it is useful for maintaining the older documentation projects. For information about current API documentation, see Documenting APIs.

Introduction

Each API has one or more resources: these are the items that outside users interact with to get the information that they want. Documenting APIs is essentially documenting these resources. 

Documentation for an API has at least four files: three .rst files created by the doc team, and a views.py file that the engineering team creates and the doc team edits. 

• index.rst: Lists the overview file and the resource_name file or files.
• overview.rst: Contains information about the current version, status, resources, possible tasks, and endpoints.
• resource_name.rst: Contains information about the resource's use case, example requests, response values, and example responses. Most of this information is pulled automatically from the views.py file for that resource. Every resource has its own resource_name.rst file. Example responses should be in the RST file, not the views.py file.
• views.py: A Python file that contains the docstrings that must be edited. These docstrings are imported into the resource_name.rst file for the resource. Every resource has its own views.py file.

For example, the Enrollment API has only one resource. For the Enrollment API, documentation consists of the following files.

• views.py
• index.rst
• overview.rst
• enrollment.rst 

The Mobile API has three separate resources: course_info, users, and video_outlines. Each resource has its own .rst file and its own views.py file. The Mobile API documentation consists of the following files.

• index.rst
• overview.rst
• course_info.rst
• course_info/views.py
• users.rst
• users/views.py
• video_outlines.rst
• video_outlines/views.py

Step 1: Assemble Information

To document resources, you need two documents. The engineering team creates both of these documents and should let you know where they are.

• The views.py file for each resource
• The API spec

views.py

Views.py files are always inside a djangoapps/API_Name folder, but the location of that folder varies, and the views.py file will be in a djangoapps/API_Name/Resource_Name folder if the API has multiple resources. Example paths to several different views.py files follow.

edx-platform/lms/djangoapps/mobile_api/course_info/views.py (resource 1 of 3)

edx-platform/lms/djangoapps/mobile_api/users/views.py (resource 2 of 3)

edx-platform/lms/djangoapps/mobile_api/video_outlines/views.py (resource 3 of 3)

edx-platform/openedx/core/djangoapps/user_api/accounts/views.py (resource 1 of 2)

edx-platform/openedx/core/djangoapps/user_api/preferences/views.py (resource 2 of 2)

edx-platform/openedx/core/djangoapps/bookmarks/views.py

edx-platform/openedx/core/djangoapps/profile_images/views.py

edx-platform/common/djangoapps/enrollment/views.py

API specs

These are usually wiki pages. To become acquainted with API specs, see the following documents.

• Bookmarks API spec
• User API spec

Step 2: Edit the Doc Strings in the views.py File for Each Resource

After you find the views.py file for each resource, you edit the doc string in that file.

For more example API doc strings, see Example API Doc Strings.

In the views.py file for each resource, locate a section that starts with a class and contains the following headings. 

• Use Case or Use Cases (required)
• Example Request or Example Requests (required)
  • Method_Name Parameters (optional) (for example, POST Parameters) (there may be more than one of these - for example, there may be GET Parameters and POST Parameters headings)
• Response Values (required) (there may be more than one of these - for example, there may be GET Response Values and POST Response Values headings)

This class section is the doc string for the resource. The views.py file may contain more than one class section. When you create the page for the individual resource, you create a heading for each class.

This section may be short, as in the following example, or long. 

Edit all of the text in this section, keeping the following guidelines in mind.

• **Example Requests** frequently has a trailing colon; make sure to delete this.
   
• Values should be arranged in alphabetical order.
   
• Each response should include an HTTP response code with both the code and the name, as in the following examples.
  
  If the requesting user does not have the specified username and has staff access, the request returns an HTTP 403 "Forbidden" response. If the requesting user does not have staff access, the request returns an HTTP 404 "Not Found" response to avoid revealing the existence of the account.
  
  If the request is successful, a 204 "No Content" status is returned with no additional content.
  
  If "application/merge-patch+json" is not the specified content type, a 415 "Unsupported Media Type" response is returned.
   
• If possible, the views.py file should list HTTP responses for both successful requests and errors.
   
• Lines in the views.py file should wrap at the standard 80 characters (you can use Ctrl+Alt+Q), with the exception of example requests. Note that you WILL get pylint errors if your lines end with a (white) space, so make sure to return immediately after the last character in each line, and not after a space.
   
• This information will be automatically pulled into an .rst file; the formatting for these .rst files is the same for other .rst files that we work with (e.g., line breaks in nested bullet lists are important).

Step 3: Create the API Folder

For platform API documentation, in the edx-platform/docs/en_us/platform_api/source/ folder, create a folder for the documentation for the API and name the folder the API name, lowercase with underscores instead of spaces. For example, for the Profile Images API, the folder is docs/en_us/platform_api/source/profile_images/.

Step 4. Create the resource_name.rst File for Each Resource

For platform API documentation, in the new edx-platform/docs/en_us/platform_api/source/api_name folder, create an .rst file for each resource. This file will contain the text that you import from the views.py file as well as example responses for the requests that the views.py file describes.

For example resource_name.rst files, see video_outlines.rst File or profile_images.rst File.

1. Create a file and name it according to the resource. Each resource must have a separate file. For example, Enrollment API only has one API file, enrollment.rst. The Mobile API has three resources, so it has files named users.rst, course_info.rst, and video_outlines.rst. 
    

2. Add an introductory sentence. Then, add a heading for each task that users can accomplish by using that resource. These tasks parallel the actions described in the "Use Cases" sections of the views.py file for that resource.
      * If one action description contains two verbs -- for example, "Get or update the ID of the module that the specified user last visited in the specified course" --  create only one heading for these two tasks.
   
   For example, the views.py file for the Preferences resource in the Users API has the following text.

    

   class PreferencesView(APIView):     """         **Use Cases**             Get or update the user's preference information. Updates are only             supported through merge patch. Preference values of null in a             patch request are treated as requests to remove the preference.         **Example Requests**             GET /api/user/v1/preferences/{username}/             PATCH /api/user/v1/preferences/{username}/ with content_type "application/merge-patch+json"

    

    The preferences.rst file has the following text.

    

   .. _User Preferences API:   ################################################## User Preferences API ##################################################   This page contains information about using the User Preferences API to complete the following actions.   .. contents::    :local:    :depth: 1   .. _Get or Update User Preferences Information:   ************************************************** Get or Update the User's Preferences Information **************************************************

3. Under the heading for the tasks that are associated with the particular class, use the autoclass directive to import the doc strings that you edited in the views.py file into the resource_name.rst file. To do this, you need three things. 

   • The name of the folder that contains the views.py file.
   • "views" (without the quotation marks).
   • The name of the class (without "(APIView)").

   Separate these with periods.

    

   .. autoclass:: folder_name.views.class_name

    

    For example:

    

   .. autoclass:: user_api.preferences.views.PreferencesView

4. Under the autoclass directive, use bold text (not headings) to create an Example Response section, and then add an example response for the example request in the views.py file. You can get an example response from the API spec. For a sample API spec, see Bookmarks API.
   
   Note: Ideally, we would have one example response for each example request. We haven't always done that in the past but would like to going forward. 

5. Repeat steps 3-4 for each additional class in the views.py file.

Note, again, that each resource must have its own resource_name.rst file.

Step 5: Create the overview.rst File

For platform API documentation, in the edx-platform/docs/en_us/platform_api/source/API_Name folder, create an overview.rst file. There is only one overview.rst file for each API, no matter how many resources the API has.

For example overview.rst files, see overview.rst in Example API .rst Files, overview.rst File in Video Outlines Resource Documentation or overview.rst File in Profile Images API Documentation.

The overview.rst file contains the following sections. 

• Introduction: A brief statement about the API.
• API_Name API Version and Status: A brief statement about the version number. May also include information such as "We plan to make significant enhancements to this API." For a new API, the version number is almost always 1.
• API_Name API Endpoints: A table listing the tasks that a user can accomplish with the resources that the API has, along with the methods and endpoints to use. If the API has more than one resource, this heading will be "API_Name Resources and Endpoints", and each resource will have its own subsection with its own Task/Method/Endpoint table. 

Information for the "API_Name Endpoints" table comes from the views.py file and the API spec. 

 In the views.py file, you can find the tasks, methods, and endpoints for each resource from the Use Case and Example Request sections.

• The Task is the action listed under "Use Case" (or "Use Cases"). (You used this information when you created the resource_name.rst file for the resource.)
• The Method is the verb under "Example Request" (or "Example Requests"). This will typically be GET, PATCH, POST, PUT, or DELETE.
• The Endpoint is the text that follows the verb under "Example Request". (It is the last part of a uniform resource locator, or URL, that specifies the location of the resource.) One endpoint may have more than one associated verb. 

For example, you might see the following text in the views.py file.

In this case, you would create the following endpoints table. 

:ref:`Get a list of all videos in the specified course

 <Get video list>`

GET

/api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}

:ref:`Get the ID of the module that the specified user last visited 

in the specified course <Get or update module ID>`

GET

/api/mobile/v0.5/users/{username}/course_status_info/{course_id}

:ref:`Update the ID of the module that the specified user last visited 

in the specified course <Get or update module ID>`

PATCH

/api/mobile/v0.5/users/{username}/course_status_info/{course_id}

Note that you can only use the endpoint that appears in the views.py file example request if the example includes placeholders instead of "real" values. If the example request contains non-placeholder values, as in the following example, you can look in the "Endpoints" section of the API spec for the correct endpoint.

Step 6: Create the index.rst File

In the edx-platform/docs/en_us/platform_api/source/API_Name folder, create an index.rst file. Include entries for the following files.

• overview
• API or Resource 1 Name
• API or Resource 2 Name (if any)

For more information, see the index.rst examples in Example API .rst Files.

Step 7. Update Source Folder Files

Add entries about the new API to the following files.

• docs/en_us/platform_api/source/change_log.rst
• docs/en_us/platform_api/source/index.rst
• docs/en_us/platform_api/source/overview.rst
  

Step 8. Update the conf.py File

Update the docs/en_us/platform_api/source/conf.py file. 

Often when adding a new module, you need to change to conf.py file in the doc project "mock" other classes that are imported into code. If build has warnings, check with Mark.

Example Files

For examples of complete API documentation in raw form, see Mobile API Documentation and Profile Images API Documentation.

For examples of doc strings in views.py files, see Example API Doc Strings.

For example index.rst and overview.rst files, see Example API .rst Files.