Author: Rashad Kanavath <firstname.lastname@example.org>
Copyright: CS-SI (for scripts in repository)
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.
- 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
- 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/