Writing documentation

Orange Widget Documentation

Documentation for Orange widgets is located in /doc/visual-programming/source. Documentation for add-ons is located in /doc.

1. Write a .md file. Feel free to use an existing doc file as template.

   • The title of the file has to correspond to the widget name.
   • Underscores have to fit the length of the title.
   • Copy-paste the widget description under the title if it exists. If not, propose one and keep it concise.
   • List inputs and outputs.
   • Describe what the widget does and how it is used. Link methods to papers or Wikipedia.
   • Add a stamped screenshot of the widget (see details below).
   • Describe each item of the widget.
   • Add Examples section. Here, explain the typical use of the widget (a simple case) and, if possible, a more advanced, interesting use. Make sure to explain the process step by step and provide a comprehensive screenshot of the entire workflow.

2. Images:

   • Each widget has to contain a screenshot of the widget on its own and a screenshot of a typical workflow. On macOs make sure to turn off window shadows! Add self.setWindowFlags(Qt.NoDropShadowWindowHint) in
     • orange-canvas-core, in orangecanvas/application/canvasmain.py, in CanvasMainWindow.__init__, after the call of inherited constructor (around L138, and in
     • orange-widget-base, in orangewidget/widget.py, in OWBaseWidget.__new__, after calls of inherited constructors (around L318).
   • To mark widget sections with numbers, run python stamper.py from orange-tools repo.
   • To create a screenshot of the workflow, set you background to a loud, ugly color. Take a screenshot. Then run python trim.py Screenshot-with-ugly-background.png from orange-tools repo. This will replace the ugly color with transparent.
   • Index images. Every image is indexed to save space. In GIMP, go to Image - Mode - Indexed and index the image. Then save it with File - Export As... For batch indexing use the script from orange-tools.
   • Place images in the corresponding images folder, e.g /widgets/data/images.

3. Build the documentation by running make htmlhelp in the doc folder (or visual-programming for core Orange). This runs sphinx build and you will see if there are any errors that need fixing. You can check the built documentation in the build folder.

4. Hints:

   • When referring to another Orange widget, you can use :doc:`Widget <../widget-doc-file>` .
   • If images get too big (e.g. on retina screens), you can scale them: {{% figure src="my-image.png" width="70%" height="70%"%}}

Generating widget.json

Widget catalog on the website is generated from the widget.json file. Widget.json is automatically generated by running:

cd doc/
python <path-to-orange>/orange-hugo/scripts/create_widget_catalog.py --categories Data,Visualize,Model,Evaluate,Unsupervised, --doc visual-programming/source/

See https://github.com/biolab/orange3/pull/4052 and https://github.com/biolab/orange3-text/pull/460 for details.

Do not manually write to this file! Always generate it with the above command. This will ensure consistency and show possible errors. The file is used for generating documentation and it extracts information on widget names, icons, background color, and keywords automatically.