Skip to content

Writing documentation

Jump to bottom
Ajda edited this page Sep 14, 2018 · 3 revisions

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 .rst/.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. This part is rendered by _static/style.css.
    • Describe what the widget does and how it is used. Link methods to papers or Wikipedia.
    • Add a stamped screenshot of the widget.
    • 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 OSX make sure to turn of window shadows.
    • 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 load, ugly color. Take a screenshot. Then run python trim.py Screenshot-with-ugly-background.png from orange-tools repo. This will extract the ugly color and replace it with transparency.
    • 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...
    • 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:: images/image.png
   :scale: 50%
Clone this wiki locally