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:

• Source
• Demo

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 Demo controllers

size

The size of the iframe that shows the widget demo. Available sizes::

small, medium, large, x-large