wsme/doc/document.rst

Document your API

Web services without a proper documentation are usually useless.

To make it easy to document your own API, WSME provides a Sphinx extension.

Install the extension

Here we consider that you already quick-started a sphinx project.

1. In your conf.py file, add 'ext' to your extensions, and optionally set the enabled protocols.

   extensions = ['ext']
   
   wsme_protocols = ['restjson', 'restxml', 'extdirect']

2. Copy toggle.js <_static/toggle.js> and toggle.css <_static/toggle.css> in your _static directory.

The wsme domain

The extension will add a new Sphinx domain providing a few directives.

Config values

wsme_protocols

A list of strings that are WSME protocol names. If provided by an additional package (for example WSME-Soap or WSME-ExtDirect), that package must be installed.

The types and services generated documentation will include code samples for each of these protocols.

wsme_root

A string that is the full name of the service root controller. It will be used to determinate the relative path of the other controllers when they are autodocumented, and calculate the complete webpath of the other controllers.

wsme_webpath

A string that is the webpath where the wsme_root is mounted.

Directives

Define the service root controller for this documentation source file. To set it globally, see wsme_root.

A webpath option allows override of wsme_webpath.

Example:

.. wsme:root:: myapp.controllers.MyWSRoot
    :webpath: /api

Declare a service.

Equivalent to the :rstpy:class directive to document a complex type

Equivalent to the :rstpy:attribute directive to document a complex type attribute. It takes an additional :type: field.

Example

Source	Result
.. wsme:root:: wsmeext.sphinxext.SampleService :webpath: /api .. wsme:type:: MyType .. wsme:attribute:: test :type: int .. wsme:service:: name/space/SampleService .. wsme:function:: doit	type int Returns a :wsmeMyType <MyType>

Autodoc directives

Theses directives scan your code to generate the documentation from the docstrings and your API types and controllers.

Generate the myapp.MyType documentation.

Generate the myapp.MyType.aname documentation.

Generate the myapp.MyService documentation.

Generate the myapp.MyService.myfunction documentation.

Full Example

Python source

../wsmeext/sphinxext.py

Documentation source

.. default-domain:: wsmeext

.. type:: int

    An integer

.. autotype:: wsmeext.sphinxext.SampleType
    :members:

.. autoservice:: wsmeext.sphinxext.SampleService
    :members:

Result

wsmeext

int

An integer

wsmeext.sphinxext.SampleType

wsmeext.sphinxext.SampleService