Render examples in the CookBook

Summary

The next step in the Software Guide migration to the rst CookBook: render examples.

• New CookBook section: C++
• Render examples in the CookBook section C++/Examples
• Rewrite two examples with the new format (see below)
  • Examples/BasicFilters/LeeImageFilter.rst
  • Examples/FeatureExtraction/TextureExample.rst
• clang-format all examples & cleanup old tags

How to write a "new style" example

• Put the .cxx file in Examples/tag/YourExample.cxx
• Use normal C++14 style (no more BeginLatex/BeginCmdLineArgs/etc)
• At the top of the .cxx file there must be a "usage" comment with the following syntax:

/* Example usage:
./TextureExample Input/ADS40RoiSmall.png Output/TextureOutput.tif Output/pretty_TextureOutput.png 2 1 1
*/

• (Optional) Write a description in Examples/tag/YourExample.rst. You may include figures from otb-data/Input or otb-data/Output (e.g. the output of your example) with the "absolute path" syntax, for example:

.. figure:: /Output/pretty_TextureOutput.png

    Result of applying the ScalarImageToTexturesFilter to an image (contrast).

• Run your example and add the figures needed for the description in otb-data/Output.

How to run examples

Contrary to the software guide, examples are not run when building the CookBook. They can be run manually using a new script: Documentation/Cookbook/Scripts/RunExamples.py. You can run all examples or only one. For example, in an OTB build directory do:

RunExamples.py /path/to/otb /path/to/otb-data

or:

RunExamples.py /path/to/otb /path/to/otb-data --name TextureExample

TODO in future work:

• Update all examples from old latex format to new rst format
  • Remove \doxygen and \code macros
  • Replace \includegraphics{} directives with .. figure:: filename.png in the .rst file
  • Add needed .png figures to otb-data/Output
• Remove examples tests
• Remove examples tests baselines
• Add RunExamples.py script in a new test
• Fix missing usages
• Improve RunExamples.py to be able to run in another working directory than otb-data
• Modernize examples to C++14
• Continue migrating Software Guide sections that are not examples
• Improve license header filtering in rst render (itk copyright)
• Handle ApplicationExample
• Move Documentation/Cookbook/Art/ to Data/ after the LFS migration is complete

Rationale

#1679

Implementation Details

Most of the implementation is in the new scripts Documentation/Cookbook/Scripts/otbGenerateWrappersRstDoc.py and Documentation/Cookbook/Scripts/RunExamples.py.

The "usage" command is extracted from the cxx source code with this regex: \/\* Example usage:\n(\.\/[a-zA-Z]+ (.*?))\*\/.

otb-data

Changes in otb-data (otb-data!16 (merged)) are adding the examples outputs that are needed for the examples:

A       Output/GomaSmallLeeFiltered.png
A       Output/pretty_TextureOutput.png

As we improve the old examples or add new ones, figures can be added in Documentation/Cookbook/Art/ if they are static, or otb-data/Output if they are the output of an example.

Copyright

The copyright owner is CNES and has signed the ORFEO ToolBox Contributor License Agreement.

---

Check before merging:

• All discussions are resolved
• At least 2 votes from core developers, no vote.
• The feature branch is (reasonably) up-to-date with the base branch
• Dashboard is green
• Copyright owner has signed the ORFEO ToolBox Contributor License Agreement