.. _embed:

Embedding the WidgetBrowser in Sphinx docs
==========================================

The WidgetBrowser includes a Sphinx extension to embed a widget browser inside
generated docs to show a demo of a widget.

Enable the extension
--------------------

In the `conf.py` configuration file Sphinx uses add the following lines after
`extensions` is declared::

    try:
        import widgetbrowser
        extensions.append("widgetbrowser.sphinx_ext")
    except ImportError:
        pass

It is recommended to first try to import `widgetbrowser` to see if it is
installed so users can build the docs regardless if WidgetBrowser is installed
otr not. If it isn't, Sphinx will just emitt warnings when it finds the
`widgetbrowser` directive it doesn't understand.

Using the `widgetbrowser` directive
-----------------------------------

To insert a widget browser a special reStructuredText directive is used which
looks like this::
    
    .. widgetbrowser:: tw.forms.samples.AddUserForm
       :tabs: source, demo
       :size: x-large

And produces this:

.. widgetbrowser:: tw.forms.samples.AddUserForm
   :tabs: source, demo
   :size: x-large

Options
-------

tabs
    A comma-separated lists of tabs to display. Each will link to 
    `<widget>/<tab_name>`. To learn how to write controllers to feed
    each tab refer to :ref:`demo_controller`

size
    The size of the iframe that shows the widget demo. Available sizes::
        small, medium, large, x-large