Request for Comments-37: Guidelines for Application documentation

[Request for Comments - 37] Guidelines for Application documentation

Status

• Author: Guillaume Pasero
• Submitted on 03.07.2017
• Open for comments

Content

What changes will be made and why they would make a better Orfeo ToolBox?

Guidelines to improve the documentation embedded in OTB Applications. These guidelines will then be used in order to review and enhance the documentation in all OTB Application.

When will those changes be available (target release or date)?

Those changes can be available for release 6.2

Who will be developing the proposed changes?

The whole OTB developer Team

---

Guidelines for Application documentation

Here is a proposal for a set of Guidelines for the writing of the documentation fields in an application. The text in these fields will be processed by different tools, that will either parse it as ReStructeredText (Sphinx for CookBook) or convert it in HTML (otb::Wrapper::ApplicationHtmlDocGenerator). This is why there are some constraints on the syntax (see RST quick-reference [1], from http://docutils.sourceforge.net/rst.html).

Common rules :

• Avoid non-ASCII character
• Formulas should be written in rst syntax
• Bullet lists should follow rst syntax, for instance :

Here is my enumeration :
  * First item
  * Second item:
    - Sub item
    - Other sub item

DocName :

• should be short
• only one line
• should have a good match with the official "Name"

DocLongDescription :

• should be extensive, it should describe :
  • 1. The general purpose of the application
  • 2. The context in which it can be used (if part of a larger pipeline)
  • 3. The different modes of the application
• multiple lines advised
• may explain how the application is working, give some hints on the algorithms,
• Should never end with a newline

DocLimitations :

• should expose any limitation on the type of data handled
• should warn users if streaming is not supported
• should warn users if some data formats are not supported

DocSeeAlso :

• A list of references (other application, links, paper citations in APA style), one per line, starting with [n] to be refered to in long description.

Parameter->Name :

• should be very short
• only one line

Parameter->Description :

• Should be more extensive than the parameter name (when needed)
• multiple lines allowed
• Input parameters (images, vector or text) should specify :
  • what the input is expected to contain
  • what OTB Application may generate a suitable input
• Output parameters (images, vector or text) should specify :
  • what will contain the output
  • what OTB Application may use the generated output
• Numerical parameters should give details on :
  • their unit and admissible value range (if any)
  • the effect of this value in the algorithm, for instance by giving the behaviour for low and high values

---