Skip to content
GitLab
  • Menu
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in
  • otb otb
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 194
    • Issues 194
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 8
    • Merge requests 8
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Packages & Registries
    • Packages & Registries
    • Container Registry
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • Main Repositories
  • otbotb
  • Merge requests
  • !316

Christmas CookBook

  • Review changes

  • Download
  • Email patches
  • Plain diff
Merged Victor Poughon requested to merge xmas_cookbook into develop Dec 07, 2018
  • Overview 5
  • Commits 24
  • Changes 71

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
Edited Dec 12, 2018 by Victor Poughon
Assignee
Assign to
Reviewer
Request review from
Time tracking
Source branch: xmas_cookbook