Document your API

Web services without a proper documentation are usually useless.

The recommended way is to use the tgwsdoc Sphinx extension, which lies in the “contrib” directory.

If you don’t have the source distribution of TGWebServices, you can fetch the files from http://tgws.googlecode.com/hg/contrib/tgwsdoc/.

tgwsdoc Sphinx extension

Automatically generate documentation for TGWebService controllers and methods in the autodoc fashion with added examples.

Installing the extension

1. In your conf.py file, add “tgwsdoc” in the extensions list. If needed add the directory containing tgwsdoc.py to the path.

2. Copy “toggle.js” and “toggle.css” into the “_static” directory.

3. Add “toggle.css” to the styles.

   To do that, create a new css for your documentation (e.g. “_static/mydoc.css”) with the following content (assuming that you use the ‘default’ theme):

   @import 'default.css';
   @import 'toggle.css';
   

   In conf.py, set your new style :

   html_style = 'mydoc.css'
   

   You can of course adapt this to your needs, especially if you already have a custom style : just make sure toggle.css gets loaded by the browser.

Added directives

.. autotgwstype:: myapp.controllers.apitypes.MyComplexType

Generate a nice documentation for complex types. It includes a classic documentation of class attributes, plus two example of serialisation : one XML and one json.

If the complex type has no default constuctor (ie taking no parameter) or if one want meaningfull datas to be shown, define a “sample” method on the class. If existing, it will be used as a constructor by tgwsdoc to instanciate the class.

.. tgwsrootcontroller:: myapp.controllers.RootWebServiceController /<url>

Define, for later use by the other directives, where is the web services root. The “/<url>” is the “mount point” of your web service root controller. For example, “/api”.

.. autotgwscontroller:: myapp.controllers.AWebServiceController

Insert the docstring documentation of the controller. If a tgwsrootcontroller directive is present earlier in the rst file, the actual url of the controller (which is the base path of its methods for REST+[JSON|XML]) is calculated and inserted.

As with autoclass (from the autodoc extension), the members option will also autodocument members, but only the exposed methods will be included.

.. autotgwsfunction:: myapp.controller.AWebServiceController.anexposedmethod

Insert the docstring documentation of the function.

In addition, it computes an adapted signature for the function, and documents the parameters with links to the types definition if they exists.

Example

Given the following program :

from tgwebservices.controllers import WebServicesRoot, WebServicesController, \
                                      wsexpose, wsvalidate

from tgwebservices.runtime import typedproperty, unsigned

class FancyValue(object):
    "A person description"
    #: The name
    name = unicode
    #: The age
    age = int

    def computed(self):
        return "Hello!"

    #: A computed property
    computed = typedproperty(str, computed)

    def __init__(self, name=None, age=None):
        self.name = name
        self.age = age

    @classmethod
    def sample(cls):
        return FancyValue('Rimbaud', 27)

class FancyService(WebServicesController):
    "Fancy functions"
    @wsexpose(FancyValue)
    def getfancy(self):
        """
        Returns a fancy value

        :returns: The fancy value
        """
        fv = FancyValue()
        fv.name = "Mr. Test"
        fv.age = 33
        return fv

    @wsexpose()
    @wsvalidate(FancyValue)
    def setfancy(self, fancy):
        """Send a fancy value
        :param value: The sent fancy
        """
        return

class MyService(WebServicesRoot):
    "Basic functions"
    fancy = FancyService()

    @wsexpose(int)
    @wsvalidate(int)
    def times2(self, value):
        """
        Multiplies value by two.

        :param value: The value to multiply
        """
        return value * 2

    @wsexpose(int)
    @wsvalidate(int)
    def twentyover(self, value):
        """
        Divides 20 by value.

        :param value: The value to divide
        """
        return 20 / value

The documentation source would be :

MyService documentation
=======================

.. tgwsrootcontroller:: api.MyService /api

Types
-----

.. autotgwstype:: api.FancyValue

Functions
---------

.. autotgwscontroller:: api.MyService
    :members:

.. autotgwscontroller:: api.FancyService
    :members:

And the result :

• MyService documentation
  • Types
  • Functions