Add Ons

Structure of an Add-On

Add-on is a Python package (see Python Packaging User Guide and in particular Packaging and Distributing Projects).

The recommended structure of an Orange add-on is as follows:

orange-addonname/
    COPYING
    LICENSE
    setup.py
    docs/
        Makefile
        rst/
            conf.py
            index.rst
    packagename/
        datasets/
        widgets/
            __init__.py
        ...
        __init__.py
        ...

setup.py as prepared in Biolab's add-ons can be used to get a good starting point for a new add-on.

The docs folder contains Sphinx reST documentation of the add-on (Sphinx is the preferred documentation tool and its intersphinx mapping can be used by Orange Canvas to find/display widget documentation).

datasets contain any additional datasets add-on might provide.

Entry points (hooks)

Add-ons register through setuptools' entry points.

The following entry points are currently used by Orange:

• orange.widgets Entry point register add-on's widgets in Orange Canvas.

• orange.canvas.help Entry point to register the widget documentation (help pages) with Orange Canvas help system.

Example:

entry_points = {
    'orange.widgets': (
        'Foobar = packagename.widgets',
    ),
    'orange.canvas.help': (
        'intersphinx = packagename.widgets:intersphinxdef'
}

The first ('orange.widgets') entry point will register packagename.widgets to be searched for widget definitions by Orange Canvas (all importable modules within will be searched for a OWWidget definitions). All widgets found will be available under a category named Foobar.

The second entry point points the Orange Canvas to an intersphinx definition in packagename/widgets/__init__.py which would contain the specification for accessing sphinx based documentation:

intersphinxdef = [
    ("http://example.com/doc/", None),
    ("http://alternative.example.com/doc", None)
]

(the tuples here have the same meaning as described in [http://sphinx-doc.org/ext/intersphinx.html], except that the second entry if not None should always be an absolute path)

Then if you have a widget named 'Widget Name' you just have to make sure that in sphinx ``:ref:`Widget Name```would resolve to the proper page intended to be shown. If so then that page will be displayed when a user requests help for a widget in the Canvas

When specifying the documentation urls you can also use some string substitutions. For instance Orange itself uses this

intersphinx = (
     # root in development mode
     ("{DEVELOP_ROOT}/docs/build/html/", None),
     # URL is taken from PKG-INFO (Home-page)
     ("{URL}/docs/latest/",
      "{URL}/docs/latest/_objects/")
)

Here the first entry would resolve to the local documentation when installed in 'develop' mode, and the second to http://orange.biolab.si/docs/latest, because of the 'url' parameter passed to setup function in setup.py.

Distribution

Add-ons should be distributed through PyPi. If done so (and keyword 'orange3 add-on' is used for the package), they will be displayed among available add-ons on Orange webpage.

It is highly recommended that build wheel distributions are also uploaded to PyPi for a faster/easier installation

Installation

Installation using pip is recommended and should be supported by an add-on.