.. _`kognihome/tools/sphinx_rsbext`:

:mod:`rsbext` -- Support for advanced Scope handling
====================================================

.. module:: rsbext
   :synopsis: Provides an environment for the Definition of Scopes
.. moduleauthor:: Alexander Neumann <alneuman@techfak.uni-bielefeld.de>

This module provides 4 directives. The following 2 directives are used to define scopes.
They will not be shown though. To display collections of defined scopes refer to `Show Scopes`_.

Define Scopes
-------------

.. rst:directive:: .. rsbpubsub:: type scope message_type description

    Example::

        .. rsbpubsub:: OUT /io/display/mirror/face string Detektierte Person vor dem Spiegel

    ``rsbpubsub`` expects 4 arguments. The first 3 arguments **must not** contain whitespaces.
    The first argument defines the ``type`` of how the scope is used. Use ``IN`` to express that the
    component in question expects to receive data on this scope. Use ``OUT`` if the component sends information.

    Second, the RSB scope is expected. Third, the ``message_type`` can be a primitive (int, string, boolean) or
    an RST type, such as ``rst.generic.Value``. The ``description`` should define the purpose of the received or sent
    data in respect to the documented component.

.. rst:directive:: .. rsbrpc:: type scope method in_type out_type description

    Example::

        .. rsbrpc:: CALLS /service/kognidb/ register_app string string Registriert Anwendung 'kognichef'


    ``rsbrpc`` is used in a similar fashion. ``type`` can be either ``CALLS`` for consumer of an RPC or ``PROVIDES`` if
    the endpoint is provided by the component. ``scope`` and ``method`` are separated by a whitespace.

Show Scopes
-----------

.. rst:directive:: .. rsbpubsublist::

    Example::

        This is a list of all PubSub scopes defined in this document
        .. rsbpubsublist::

        This is a list of all components which send information on scopes related to sensors
        .. rsbpubsublist::
            :global:
            :type: OUT
            :filter: sensor

    The following options are supported:
        * ``type`` -- filter scopes by kind
        * ``global`` -- use all defined scopes
        * ``filter`` -- only show scopes that contain the filter string

    The list directive will only consider scopes defined in the same file as the directive if ``global`` is not used.
    The ``global`` option can be used to create overview sections. In combination with ``filter`` it is possible to
    create collections for complex systems.

.. rst:directive:: .. rsbrpclist::

 Example::

    .. rsbrpclist::
        :global:
        :type: PROVIDES
        :filter: register

 ``rsbrpclist`` supports the same options as ``rsbpubsublist``.