Christmas CookBook

Rationale

Improve the application documentation which currently has a lot of formatting problems, and improve the cookbook in general.

Summary

• Complete rewrite of otbGenerateWrappersRstDoc.py
• New way of presenting parameters (no more choice parameter recursive spaghetti)
• Support custom CSS
• Build CookBook without -W
• Fix #1771 (closed)
• Show "Edit on Gitlab" link
• Manual review of all applications documentation (grammar mistakes, rst warnings, dead links, broken formulas...)
• Don't show "DocName" and "Authors"
• Many small design improvements
• Add documentation warnings. Here's an example (in reality there are 100+, we can fix them in another branch)

OTB Documentation Warning (Rescale): 'ram' parameter is not third from last
OTB Documentation Warning (RigidTransformResample): Application Long Description does not end with a period (.)
OTB Documentation Warning (SARCalibration): Parameter 'lut' name contains special character (.)
OTB Documentation Warning (SARCalibration): 'ram' parameter is not third from last
OTB Documentation Warning (SARDecompositions): Application Long Description has a space before a colon
OTB Documentation Warning (SARDecompositions): Parameter 'inco.kernelsize' name contains special character (.)
OTB Documentation Warning (SARPolarMatrixConvert): Parameter 'inc' name contains special character (:)

• Make GetDocLink link to Cookbook (instead of /Applications)
• Automatic internal links in application description (e.g. if you write "BlockMatching" in the long description it will become a link).
• Fix bug in GetParameterAsString where string lists were formatted with '\n' (use space instead).
• Relax otbWrapperApplicationDocTests to allow empty Limitations, empty SeeAlso and trailing newline in LongDescription.

This branch has a corresponding branch in otb-data to update the baseline for owTvApplicationHtmlDocGeneratorTest.

Guidelines to application documentation authors

• Use rst format
• Prefer present tense imperative
• Order of parameters is important!
• Avoid useless words like "this application...." or "this parameter..."
• Avoid noise like "Input output: This allows setting input and output"

Future work

• Multiple versions with sphinxcontrib-versioning
• Fix "documentation warnings"
• Deprecate SetDocName? #1789 (closed)
• Deprecate otbWrapperApplicationHtmlDocGenerator

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