Changes between Version 15 and Version 16 of AddOns


Ignore:
Timestamp:
08/29/13 19:12:14 (8 months ago)
Author:
ales
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • AddOns

    v15 v16  
    1515            conf.py 
    1616            index.rst 
    17     _packagename/ 
     17    packagename/ 
    1818        datasets/ 
    1919        widgets/ 
     
    2727`docs` contains reST documentation of the add-on. `src` possible contains C/C++ source code. `datasets` any additional datasets add-on might use. 
    2828 
    29 Package name starts with `_` to signify it is for internal use only. Add-ons register through setuptools' entry points (hooks) into Orange namespace. Use relative imports to access other modules inside the package, if possible. 
     29Add-ons register through setuptools' entry points (hooks) into Orange namespace. 
    3030 
    3131`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. 
     
    4141 `orange.data.io.search_paths`:: 
    4242   Entry point to add add-on's datasets' directory to search path for loading datasets. 
     43 `orange.canvas.help`:: 
     44   Entry point to register the widget documentation (help pages) with Orange Canvas help system. 
    4345 
    4446Example: 
     
    4749ENTRY_POINTS = { 
    4850    'orange.addons': ( 
    49         'foobar = _packagename', 
     51        'foobar = packagename', 
    5052    ), 
    5153    'orange.widgets': ( 
    52         'Foobar = _packagename.widgets', 
     54        'Foobar = packagename.widgets', 
    5355    ), 
    5456    'orange.data.io.search_paths': ( 
    55         'packagename = _packagename:datasets', 
     57        'packagename = packagename:datasets', 
    5658    ), 
     59    'orange.canvas.help': ( 
     60        'intersphinx = packagename.widgets:some_name 
    5761} 
    5862}}} 
    5963 
    60 These entry points will inject add-on under `Orange.foobar` namespace. So `_packagename.baz` will be accessible as `Orange.foobar.baz`. 
     64These entry points will inject add-on under `Orange.foobar` namespace. So `packagename.baz` will be accessible as `Orange.foobar.baz`. 
    6165 
    6266Widgets will be available under category named `Foobar`. 
     
    6468And function `datasets` will be called to retrieve additional search paths. 
    6569 
    66 For example, accordingly to above entry point definition, it could be defined (or just exposed) in `_packagename/__init__.py` as: 
     70For example, accordingly to above entry point definition, it could be defined (or just exposed) in `packagename/__init__.py` as: 
    6771 
    6872{{{ 
     
    7377}}} 
    7478 
    75 This would add datasets in `_packagename/datasets/` to the search path, with prefix `foobar`. So: 
     79This would add datasets in `packagename/datasets/` to the search path, with prefix `foobar`. So: 
    7680 
    7781{{{ 
     
    7983}}} 
    8084 
    81 would load `_packagename/datasets/baz.tab` file. 
     85would load `packagename/datasets/baz.tab` file. 
     86 
     87 
     88Similary in `packagename/widgets/__init__.py` the `intersphinx` variable would contain the specification for accessing sphinx 
     89based documentation: 
     90{{{ 
     91some_name = [ 
     92    ("http://example.com/doc/", None), 
     93    ("http://alternative.example.com/doc", None) 
     94] 
     95}}} 
     96(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) 
     97 
     98Then 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. 
     99 
     100When specifying the documentation urls you can also use some string substitutions. For instance Orange itself uses this 
     101{{{ 
     102intersphinx = ( 
     103     # root in development mode 
     104     ("{DEVELOP_ROOT}/docs/build/html/", None), 
     105     # URL is taken from PKG-INFO (Home-page) 
     106     ("{URL}/docs/latest/", 
     107      "{URL}/docs/latest/_objects/") 
     108) 
     109}}} 
     110Here the first entry would resolve to the local documentation when installed in 'develop' mode, 
     111and the second to [http://orange.biolab.si/docs/latest], because of the 'url' parameter passed to setup function in setup.py. 
    82112 
    83113== Distribution ==