Rfc/rfc cookbook

From OTBWiki
Revision as of 14:01, 31 July 2015 by Julien.Malik (Talk | contribs) (Pros)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Author: Rashad Kanavath <rashad.kanavath@c-s.fr>

Copyright: CS-SI (for scripts in repository)

Introduction

OTB Cookbook is a great starting point for new users. It starts with introduction of OTB and Monteverdi followed build instructions for different platforms and contains a lot of fruitful recipes. It contains a documentation of all applications available in OTB. These resources are proven to be very helpful for users in the OTB community. Apart from these, they served as a quick start reference for new developers as well. The whole cookbook code is hosted in OTB-Documents repository and is written entirely in latex code.

Purpose and description

This RFC propse to move the current cookbook from latex to rst(reStructuredText). Even though latex serves just the purpose, we think rst will be a more fit. It is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system as mentioned in their homepage. There is support for math equation inside rst which we think is all important when moving from latex. Transition from rst to latex, pdf, html and others are possible with sphinx tool.

Implementation will include converting all recipe code into rst along with a python script to generate rst files for each application.

Pros

  • Reading rst file can help understand the cookbook better than reading tex file.
  • Pages can be read directly on Github which comes with a rst rendering engine (with images), for example https://github.com/CS-SI/rstdocs/blob/master/Monteverdi.rst (good for contributors)
  • Small learning curve compared to Latex.
  • First step for a collaborative documentation via online tools for example (TODO : list some tools)
  • The html rendering is way more appealing than what provides the current latex2html

Cons

  • None.

Target release

  • OTB 5.2.0

Who will be developing the proposed changes

Rashad Kanavath (CS-SI)

Proposed implementation is available here: https://github.com/CS-SI/rstdocs

First results is here: http://otbcb.readthedocs.org/en/latest/

References

Comments

  • None