Building documentation for add ons

1. In your project:
   mkdir doc
cd doc
mkdir widgets
cd widgets
mkdir images
mkdir icons
   

2. Add .rst documentation files to doc/widgets.
   Add .png icons to doc/widgets/icons.
   Add .png images to doc/widgets/images.
   

3. In doc/ run:
   sphinx-quickstart
   Follow instructions. This will create a makefile, make.bat, conf.py and index.rst.
   

4. In conf.py uncomment line 46 and set source_encoding = 'utf-8'
   

5. In orangecontrib/name_of_addon/widgets/__init__.py add (with the final URL fixed):
   # Location of widget help files.
WIDGET_HELP_PATH = (
# Used for development.
# You still need to build help pages using
# make htmlhelp
# inside doc folder
("{DEVELOP_ROOT}/doc/_build/htmlhelp/index.html", None),
   

   # Online documentation url, used when the local documentation is available.
# Url should point to a page with a section Widgets. This section should
# includes links to documentation pages of each widget. Matching is
# performed by comparing link caption to widget name.
("http://orange3-name_of_project.readthedocs.io/en/latest/", "")
   

6. In setup.py add as the final entry point to ENTRY_POINTS (with the final URL fixed):
   # Register widget help
"orange.canvas.help": (
'html-index = orangecontrib.name_of_project.widgets:WIDGET_HELP_PATH',),
   

7. python setup.py develop
   

8. cd doc
make htmlhelp
   

9. Test whether F1 works on your local build and if it does, push to Github.

Widget matches documentation file comparing widget name (not file name) and documentation title (not file name). Widget name and title must be the same.

!Note! html help will only work with recommonmark==0.4.0 and CommonMark==0.5.4. Does not work well with CommonMark==0.7.3.