Add Ons

Add-ons

Structure

Add-on is a Python package. The recommended structure of an add-on repository is as follows:

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

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 used by Orange:

• orange.addons
  Entry point to register add-on into Orange namespace (deprecated).

• orange.data.io.search_paths
  Entry point to add add-on's datasets' directory to search path for loading datasets.

• 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.addons': (
        'foobar = packagename',
    ),
    'orange.widgets': (
        'Foobar = packagename.widgets',
    ),
    'orange.data.io.search_paths': (
        'packagename = packagename:datasets',
    ),
    'orange.canvas.help': (
        'intersphinx = packagename.widgets:intersphinxdef'
}

The first entry points will inject add-on under Orange.foobar namespace. So packagename.baz will be accessible as Orange.foobar.baz.

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

And function datasets in packagename module will be called to retrieve additional search paths. For example, accordingly to above entry point definition, it could be defined in packagename/__init__.py as:

import pkg_resources

def datasets():
    yield ('foobar', pkg_resources.resource_filename(__name__, 'datasets'))

This would add datasets in packagename/datasets/ to the search path, with prefix foobar, so:

data = Orange.data.Table("foobar:baz.tab")

would load packagename/datasets/baz.tab file.

Similary in packagename/widgets/__init__.py the intersphinx variable 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.

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 'orange add-on' is used for the package), they will be displayed among available add-ons on Orange webpage.

Care should be taken that add-ons work also as Python eggs. They should be uploaded for Python 2.6 and 2.7 to PyPi (along the add-on's source package) for add-on to be available for install through Orange Canvas. Installation

Installation

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

Recommended release procedure

Initial release

For your first release of Orange add-on:

• make sure code is ready

• make sure your documentation is ready, that index explains what add-on is and does and how can be installed and used

• compare your setup.py with one of Biolab's add-ons (like bioinformatics add-on)

  • make sure entry points (hooks) are defined properly
  • package must have keyword orange add-on for it to be displayed on add-ons list

• prepare README.rst file which should be included in setup.py as long description of the package – this will be used on the list of add-ons, it is useful that there is some link to documentation in there

• commit everything

• increase version in setup.py (commit message is often just 'Version bump'.)

• commit

• tag the commit with (hg tag <version string>)

• push to Github/Bitbucket

• register on ReadTheDocs and import your new Python package (for tags use also 'orange' and 'data mining')

• on Bitbucket/Github enable service integration with ReadTheDocs for your package repository, so that every time you push to the repository, documentation will be rebuilt

• publish package on PyPi (you will be prompted to register an account, if you do not have one)

    python setup.py register
    python setup.py sdist upload
    python2.6 setup.py bdist_egg upload
    python2.7 setup.py bdist_egg upload 
  

• In around one hour it should be visible on add-ons list.

Subsequent releases

When a new release is ready:

• increase version in setup.py (commit message is often just Version bump.)
• commit
• tag the commit with (hg tag <version string>)
• push to Bitbucket/github
• python setup.py register
• python setup.py sdist upload
• python2.6 setup.py bdist_egg upload
• python2.7 setup.py bdist_egg upload