Request for Changes-57: Migrate Cookbook to RST

From OTBWiki
Jump to: navigation, search

[Request for Changes - 57] Migrate Cookbook to RST

Status

  • Author: Victor Poughon and Rashad Kanavath
  • Additional Contributors (if different than authors)
  • Submitted on 01.09.2016
  • Proposed target release 5.8
  • Adopted (+3 from Victor, Julien, Rémi)
  • Merged : 6a382c43b2a7b7470784f84a8590d807492c529a

Summary

Good documentation is very important! Following RFComments-5, this branch does two things

1. Convert to RST format and the Sphinx build system.

2. Move the sources to OTB main git repository in Documentation/Cookbook

You can see the new cookbook here: https://www.orfeo-toolbox.org/packages/doc/tests-rfc-52/cookbook-20e42e3ac/

Rationale

The conversion to RST is done to improve the quality of the layout and rendering, to enable easier contributions from outside the core OTB team and is searchable with the readthedocs theme. Additionally, RST has better html rendering than latex, an easier learning curve, and renders directly on github (as noted in RFComments-5).

The move to the OTB source tree is done for the same reasons we move the Software Guide and Monteverdi. The cookbook follows the same release schedule and procedures as the rest of OTB, and therefore otb-documents has to be kept in sync manually. This will simplify both development and release processes.

The major downside to this migration is that git history is lost.

Implementation details

Building the new cookbook requires Sphinx and is as simple as:

   mkdir build-cookbook
   cd build-cookbook
   cmake path/to/otb/source/Documentation/Cookbook -DOTB_DIR=path/to/otb/build/lib/cmake/OTB-X.Y
   make

The conversion was done with pandoc, with manual corrections of some formatting errors. OTB applications documentation is generated at compile time with a script (otbGenerateWrappersRstDoc.py).

Classes and files

A	Documentation/Cookbook/Art/CNES_nom.eps
A	Documentation/Cookbook/Art/ClassifImages/samplesselect1.png
A	Documentation/Cookbook/Art/ClassifImages/samplesselect2.png
A	Documentation/Cookbook/Art/QtImages/qgis-otb-settings.png
A	Documentation/Cookbook/Art/QtImages/qgis-otb.png
A	Documentation/Cookbook/Art/QtImages/rescale_documentation.png
A	Documentation/Cookbook/Art/QtImages/rescale_logs.png
A	Documentation/Cookbook/Art/QtImages/rescale_param.png
A	Documentation/Cookbook/Art/QtImages/rescale_progress.png
A	Documentation/Cookbook/Art/S1-VV-despeckled-extract.png
A	Documentation/Cookbook/Art/S1-VV-extract-int.png
A	Documentation/Cookbook/Art/SARImages/RSAT2_HH_Frisco.png
A	Documentation/Cookbook/Art/SARImages/RSAT2_HV_Frisco.png
A	Documentation/Cookbook/Art/SARImages/RSAT2_VV_Frisco.png
A	Documentation/Cookbook/Art/SARImages/S1-VV-despeckled-extract.png
A	Documentation/Cookbook/Art/SARImages/S1-VV-extract-int.png
A	Documentation/Cookbook/Art/SARImages/alphahot.png
A	Documentation/Cookbook/Art/SARImages/anisotropyhot.png
A	Documentation/Cookbook/Art/SARImages/entropyhot.png
A	Documentation/Cookbook/Art/SARImages/sarpol_conversion_schema.png
A	Documentation/Cookbook/Art/SARImages/test-left-co-2.png
A	Documentation/Cookbook/Art/SARImages/test-left-cross-2.png
A	Documentation/Cookbook/Art/SARImages/visuPauli.png
A	Documentation/Cookbook/Art/alphahot.png
A	Documentation/Cookbook/Art/anisotropyhot.png
A	Documentation/Cookbook/Art/entropyhot.png
A	Documentation/Cookbook/Art/logo.png
A	Documentation/Cookbook/Art/logoVectoriel.eps
A	Documentation/Cookbook/Art/sarpol_conversion_schema.png
A	Documentation/Cookbook/Art/test-left-co-2.png
A	Documentation/Cookbook/Art/test-left-cross-2.png
A	Documentation/Cookbook/CMake/RunApplicationsRstGenerator.sh.cmake.in
A	Documentation/Cookbook/CMakeLists.txt
A	Documentation/Cookbook/README.md
A	Documentation/Cookbook/Scripts/otbGenerateWrappersRstDoc.py
A	Documentation/Cookbook/rst/Applications.rst
A	Documentation/Cookbook/rst/Applications/Calibration.rst
A	Documentation/Cookbook/rst/Applications/Feature_Extraction.rst
A	Documentation/Cookbook/rst/Applications/Geometry.rst
A	Documentation/Cookbook/rst/Applications/Image_Filtering.rst
A	Documentation/Cookbook/rst/Applications/Image_Manipulation.rst
A	Documentation/Cookbook/rst/Applications/Learning.rst
A	Documentation/Cookbook/rst/Applications/Miscellaneous.rst
A	Documentation/Cookbook/rst/Applications/Segmentation.rst
A	Documentation/Cookbook/rst/Applications/Stereo.rst
A	Documentation/Cookbook/rst/Applications/Vector_Data_Manipulation.rst
A	Documentation/Cookbook/rst/Installation.rst
A	Documentation/Cookbook/rst/Makefile.in
A	Documentation/Cookbook/rst/Monteverdi.rst
A	Documentation/Cookbook/rst/OTB-Applications.rst
A	Documentation/Cookbook/rst/Recipes.rst
A	Documentation/Cookbook/rst/conf.py.in
A	Documentation/Cookbook/rst/index.rst
A	Documentation/Cookbook/rst/recipes/bandmathx.rst
A	Documentation/Cookbook/rst/recipes/featextract.rst
A	Documentation/Cookbook/rst/recipes/improc.rst
A	Documentation/Cookbook/rst/recipes/numpy.rst
A	Documentation/Cookbook/rst/recipes/optpreproc.rst
A	Documentation/Cookbook/rst/recipes/pbclassif.rst
A	Documentation/Cookbook/rst/recipes/pleiades.rst
A	Documentation/Cookbook/rst/recipes/residual_registration.rst
A	Documentation/Cookbook/rst/recipes/sarprocessing.rst
A	Documentation/Cookbook/rst/recipes/stereo.rst
A	Documentation/Cookbook/rst/requirements.txt

Applications

N.A.

Tests

N.A.

Documentation

Cookbook and application documentation only. This branch also contains some improvements to the cookbook not present in otb-documents: chapter layout, typos and updated images.

Additional notes

TODO:

  • remove otbcb.readthedocs.io and host this on otb packages (trunk and stable)
  • Update How to Release procedure
  • Update nightly build platforms
  • git rm/deprecate cookbook in otb-documents
  • impose rst documentation inside otb application docs (future rfc)
  • Try to add "edit on github links": https://github.com/snide/sphinx_rtd_theme/issues/314