.. for help on writing/extending this file, see the reStructuredText cheatsheet
   http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
   
Writing documentation
=====================

This quick tutorial will guide you through the creation/modification of documentation for Natron and the plugins.

Plugins
-------

Editing/adding documentation for the Natron plugins requires you to edit the CPP file for each plugin. Usually the plugin(s) has a **kPluginDescription** define where you can edit the description found when hovering or clicking the **?** button in Natron. 

Let's start with an example, you want to edit the description in the Checkerboard plugin.

1. Fork the https://github.com/devernay/openfx-misc repository on Github.
2. Open the file *Checkerboard/Checkerboard.cpp* in your favorite (plain) text-editor

Navigate to the line **#define  kPluginDescription**, where you can edit the description. Line breaks are added with *\\n*. 

You will also notice that each parameter has a hint define, for example the Checkerboard has **#define kParamBoxSizeHint**, **#define kParamColor0Hint** etc. These describe each parameter in the plugin and shows up when you hover the parameter in Natron, or access the HTML documentation online or through Natron.

To test your modification you must build the plugin(s) and load them in Natron, refer to each plugin bundle on Github on how to build the plugin(s).

When you are done do a pull request on the master repository on Github.

Markdown
~~~~~~~~

The plugin description and parameters supports `Markdown <https://daringfireball.net/projects/markdown/syntax>`_ format. This enables you to have more control over how the information is displayed.

Enabling Markdown on a plugin requires some modifications, as the plugin must tell the host (Natron) that it supports Markdown on the description and/or parameters. See the `Shadertoy <https://github.com/devernay/openfx-misc/blob/master/Shadertoy/Shadertoy.cpp>`_ plugin for an example of how this works.

Basically you need to add **desc.setPluginDescription(kPluginDescriptionMarkdown, true);** in the **describe** function for each plugin. If you are not comfortable with this, contact the repository maintainer(s) and ask them to enable Markdown for you.

Natron
------

Contributing to the Natron documentation is a bit easier than contributing to the plugins. First fork the Natron repository on Github, https://github.com/MrKepzie/Natron. The source for the documentation is located in the *Documentation/source* folder. 

The documentation is generated using `Sphinx <http://www.sphinx-doc.org>`_, and the source files are in `reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ format.

Most likely you will want to contribute to the User Guide. The guide is located in *Documentation/source/guide*. If you want to contribute to an already existing document just open the file in your favorite (plain) text-editor and do your modifications.

If you want to preview your modifications you will need to install Sphinx. On Linux and Mac you can install it through your package manager (using MacPorts type ``sudo port install py27-sphinx``, on HomeBrew type ``pip install sphinx``), on Windows refer to the `Sphinx documentation <http://www.sphinx-doc.org/en/stable/install.html#windows-install-python-and-sphinx>`_.

When you have Sphinx installed go to the Documentation folder and launch the following command:

                sphinx-build -b html source html

The Natron documentation has now been generated in the *Documentation/html* folder. Open *Documentation/html/index.html* in your web browser to review your changes.

When your are satisfied with your modifications do a pull request against the master repository on Github.

.. note:: do not modify the files in *Documentation/source/plugins*, these are automatically generated by Natron and updated when needed.