wiki:AddOns

Version 17 (modified by ales, 8 months ago) (diff)

Add-ons

Structure

Add-on is a  Python package. The structure of an add-ons repository is as follows, package name being a name of a directory of the add-on's Python package, often lowercased addonname:

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

docs contains reST documentation of the add-on. src possibly contains C/C++ source code. datasets any additional datasets add-on might use.

Add-ons register through setuptools' entry points (hooks) into Orange namespace.

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

Entry points (hooks)

The following  entry points are defined and used by Orange:

orange.addons
Entry point to register add-on into Orange namespace.
orange.widgets
Entry point to add add-on's widgets to Orange canvas.
orange.data.io.search_paths
Entry point to add add-on's datasets' directory to search path for loading datasets.
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:some_name
}

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

Widgets will be available under category named Foobar.

And function datasets will be called to retrieve additional search paths.

For example, accordingly to above entry point definition, it could be defined (or just exposed) 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:

some_name = [
    ("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 using pip is recommended and should be supported by an add-on. Other way of installing is simply by putting add-on's Python egg into one of Python's sitedirs.

Recommended release procedure

Initial release

For your first release of Orange add-on:

  1. make sure code is ready
  2. make sure your documentation is ready, that index explains what add-on is and does and how can be installed and used
  3. compare your setup.py with one of Biolab's add-ons (like bioinformatics add-on)
    1. make sure entry points (hooks) are defined properly
    2. package must have keyword orange add-on for it to be displayed on add-ons list
  4. 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
  5. commit everything
  6. increase version in setup.py (commit message is often just Version bump.)
  7. commit
  8. tag the commit with (hg tag <version string>)
  9. push to Bitbucket
  10. register on ReadTheDocs and import your new Python package
    1. for tags use also orange and data mining
  11. on Bitbucket enable service integration with ReadTheDocs for your package repository, so that every time you push to the repository, documentation will be rebuilt
  12. publish package on PyPi (you will be prompted to register an account, if you do not have one)
    1. python setup.py register
    2. python setup.py sdist upload
    3. python2.6 setup.py bdist_egg upload
    4. python2.7 setup.py bdist_egg upload
  13. In around one hour it should be visible on add-ons list.

Subsequent releases

When a new release is ready:

  1. increase version in setup.py (commit message is often just Version bump.)
  2. commit
  3. tag the commit with (hg tag <version string>)
  4. push to Bitbucket
  5. python setup.py register
  6. python setup.py sdist upload
  7. python2.6 setup.py bdist_egg upload
  8. python2.7 setup.py bdist_egg upload