Render examples in the CookBook (!395) · Merge Requests · Main Repositories / otb

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

#### 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:

```cpp
/* 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:

```rst
.. 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:

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

or:

```bash
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) 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.

<hr>

***Check before merging:***

- All discussions are resolved
- At least 2 :thumbsup: votes from core developers, no :thumbsdown: 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 Mar 01, 2019 by Victor Poughon