Difference between revisions of "Request for Changes-57: Migrate Cookbook to RST"
(→Summary) |
(→Implementation details) |
||
| Line 30: | Line 30: | ||
Building the new cookbook requires Sphinx and is as simple as: | Building the new cookbook requires Sphinx and is as simple as: | ||
| − | mkdir build-cookbook | + | mkdir build-cookbook |
| + | cd build-cookbook | ||
cmake path/to/otb/source/Documentation/Cookbook -DOTB_DIR=path/to/otb/build/lib/cmake/OTB-X.Y | cmake path/to/otb/source/Documentation/Cookbook -DOTB_DIR=path/to/otb/build/lib/cmake/OTB-X.Y | ||
make | make | ||
Revision as of 17:19, 24 August 2016
Contents
[Request for Changes - 52] Migrate Cookbook to RST
Status
- Author: Victor Poughon and Rashad Kanavath
- Additional Contributors (if different than authors)
- Submitted on dd.mm.yyyy
- Proposed target release 5.8
- Adopted (if voted for), Rejected (if voted against), Merged in OTB x.y (if merged)
- https://git.orfeo-toolbox.org/otb.git/shortlog/refs/heads/cookbook
Summary
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
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 to enable use on the readthedocs website : [[1]]. 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.
Classes and files
TODO
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:
- Update otbcb.readthedocs.io
- Update How to Release procedure
- Update nightly build platforms
- git rm cookbook in otb-documents
