Skip to content

GitLab

Merged
Opened by Victor Poughon@poughovContributor

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
Edited by Victor Poughon