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. 

...

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.

...

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.

...

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

...