Requests for Comments-5: Move current Cookbook from Latex to reStructuredText (RST) format

From OTBWiki
Jump to: navigation, search

Status

  • Submitted by Rashad Kanavath(CS-SI) on 30/07/2015
  • Votes pending

Content

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.

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

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.

  • 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
When will those changes be available (target release or date)

These changes will be available for next release (OTB 5.2)

Proposed implementation is available here: https://github.com/CS-SI/OTB-Documents/tree/rst_cookbook

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