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.

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

    .. code-block:: python

        extensions = ['ext']

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

#.  Copy :download:`toggle.js <_static/toggle.js>`
    and :download:`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
~~~~~~~~~~~~~

.. confval:: wsme_protocols

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

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

.. confval:: 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.

.. confval:: wsme_webpath

    A string that is the webpath where the :confval:`wsme_root` is mounted.

Directives
~~~~~~~~~~

.. rst:directive:: .. root:: <WSRoot full path>

    Allow to define the service root controller in one documentation source file.
    To set it globally, see :confval:`wsme_root`.

    A ``webpath`` option allow to override :confval:`wsme_webpath`.
    
    Example:

    .. code-block:: rst

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

.. rst:directive:: .. service:: name/space/ServiceName

    Declare a service.

.. rst:directive:: .. type:: MyComplexType

    Equivalent to the :rst:dir:`py:class` directive to document a complex type

.. rst:directive:: .. attribute:: aname

    Equivalent to the :rst:dir:`py:attribute` directive to document a complex type
    attribute. It takes an additionnal ``:type:`` field.

Example
~~~~~~~

.. list-table::
    :header-rows: 1

    * - Source
      - Result

    * - .. code-block:: rst

            .. wsme:root:: wsmeext.sphinxext.SampleService
                :webpath: /api

            .. wsme:type:: MyType

                .. wsme:attribute:: test

                    :type: int

            .. wsme:service:: name/space/SampleService
                
                .. wsme:function:: doit
                    
      - .. wsme:root:: wsmeext.sphinxext.SampleService
            :webpath: /api

        .. wsme:type:: MyType

            .. wsme:attribute:: test

                :type: int

        .. wsme:service:: name/space/SampleService
            
            .. wsme:function:: getType
                
                Returns a :wsme:type:`MyType <MyType>`


Autodoc directives
~~~~~~~~~~~~~~~~~~

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

.. rst:directive:: .. autotype:: myapp.MyType

    Generate the myapp.MyType documentation.

.. rst:directive:: .. autoattribute:: myapp.MyType.aname

    Generate the myapp.MyType.aname documentation.

.. rst:directive:: .. autoservice:: myapp.MyService

    Generate the myapp.MyService documentation.

.. rst:directive:: .. autofunction:: myapp.MyService.myfunction

    Generate the myapp.MyService.myfunction documentation.

Full Example
------------

Python source
~~~~~~~~~~~~~

.. literalinclude:: ../wsmeext/sphinxext.py
    :lines: 42-67
    :language: python

Documentation source
~~~~~~~~~~~~~~~~~~~~

.. code-block:: rst

    .. default-domain:: wsmeext

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

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

Result
~~~~~~

.. default-domain:: wsmeext

.. type:: int

    An integer

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

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


.. _Sphinx: http://sphinx.pocoo.org/