ENH: add documentation warnings

Documentation/Cookbook/Scripts/otbGenerateWrappersRstDoc.py

@@ -26,6 +26,8 @@ import argparse
 import otbApplication
 from otbApplication import ParameterType_Bool, ParameterType_Int, ParameterType_Radius, ParameterType_RAM, ParameterType_Float, ParameterType_String, ParameterType_StringList, ParameterType_InputFilename, ParameterType_OutputFilename, ParameterType_InputImage, ParameterType_ComplexInputImage, ParameterType_OutputImage, ParameterType_ComplexOutputImage, ParameterType_InputVectorData, ParameterType_OutputVectorData, ParameterType_Directory, ParameterType_Choice, ParameterType_InputImageList, ParameterType_InputVectorDataList, ParameterType_InputFilenameList, ParameterType_InputProcessXML, ParameterType_OutputProcessXML, ParameterType_ListView, ParameterType_Group
 
+from otb_warnings import application_documentation_warnings
+
 linesep = os.linesep
 pixeltypes = {' uchar' : 1, ' int8' : 0, ' uint8' : 1, ' int16' : 2, ' uint16': 3, ' int32' : 4, ' uint32' : 5, ' float' : 6, ' double': 7}
 
@@ -348,12 +350,16 @@ def render_see_also(app):
     else:
         return rst_section("See also", "-") + see_also
 
-def ApplicationToRst(appname):
+def render_application(appname):
+    "Render app to rst"
+
     app = otbApplication.Registry.CreateApplication(appname)
 
     # TODO: remove this when bug 440 is fixed
     app.Init()
 
+    application_documentation_warnings(app)
+
     parameters = rst_parameters(app)
 
     output = template_application.format(
@@ -381,62 +387,49 @@ def RstPageHeading(text, maxdepth, ref=None):
     return output
 
 def GenerateRstForApplications(rst_dir):
-    out = ""
+    "Generate .rst files for all applications"
+
     blackList = ["TestApplication", "Example", "ApplicationExample"]
-    allApps = None
-    try:
-        allApps = otbApplication.Registry.GetAvailableApplications( )
-    except:
-        print('error in otbApplication.Registry.GetAvailableApplications()')
-        sys.exit(1)
+    allApps = otbApplication.Registry.GetAvailableApplications()
 
     if not allApps:
-        print('No OTB applications available. Please check OTB_APPLICATION_PATH env variable')
-        sys.exit(1)
+        raise RuntimeError("No OTB applications available. Please check OTB_APPLICATION_PATH env variable.")
 
     writtenTags = []
     appNames = [app for app in allApps if app not in blackList]
 
     appIndexFile = open(rst_dir + '/Applications.rst', 'w')
     appIndexFile.write(RstPageHeading("Applications", "2", ref="apprefdoc"))
-    for appName in appNames:
-        tags = GetApplicationTags(appName)
-
-        if not tags:
-            print("No tags for application: "  +  appName)
-            sys.exit(1)
 
-        tag = tags[0]
+    print("Generating rst for {} applications".format(len(appNames)))
 
-        tag_ = tag
-        if tag.find(' '):
-            tag_ = tag.replace(' ', '_')
+    for appName in appNames:
 
-        if not tag_:
-            print('empty tag found for ' + appName)
+        # Get application first tag
+        tags = GetApplicationTags(appName)
+        if not tags or len(tags) == 0:
+            raise RuntimeError("No tags for application: " + appName)
+        tag = tags[0].replace(' ', '_')
 
-        if not tag_ in writtenTags:
-            appIndexFile.write('\tApplications/' + tag_ + '.rst' + linesep)
-            writtenTags.append(tag_)
+        # Add it to the index (i.e. https://www.orfeo-toolbox.org/CookBook/Applications.html)
+        if not tag in writtenTags:
+            appIndexFile.write('\tApplications/' + tag + '.rst\n')
+            writtenTags.append(tag)
 
-        tagFileName = rst_dir + '/Applications/'  + tag_ + '.rst'
+        # Create or update tag index file (e.g. https://www.orfeo-toolbox.org/CookBook/Applications/Feature_Extraction.html)
+        tagFileName = rst_dir + '/Applications/'  + tag + '.rst'
         if os.path.isfile(tagFileName):
-            tagFile = open(tagFileName, 'a')
-            tagFile.write("\tapp_" + appName + linesep)
-            tagFile.close()
+            with open(tagFileName, 'a') as tagFile:
+                tagFile.write("\tapp_" + appName + "\n")
         else:
-            tagFile = open(tagFileName, 'w')
-            tagFile.write( RstPageHeading(tag, "1") )
-            tagFile.write("\tapp_" + appName + linesep)
-            tagFile.close()
-
-        print("Generating " + appName + ".rst" +  " on tag " + tag_)
-        appFile = open(rst_dir + '/Applications/app_'  + appName + '.rst', 'w')
-        out = ApplicationToRst(appName)
-        appFile.write(out)
-        appFile.close()
-
-    return out
+            with open(tagFileName, 'w') as tagFile:
+                tagFile.write( RstPageHeading(tag, "1") )
+                tagFile.write("\tapp_" + appName + "\n")
+
+        # Write application rst
+        #print("Generating " + appName + ".rst" +  " on tag " + tag)
+        with open(rst_dir + '/Applications/app_'  + appName + '.rst', 'w') as appFile:
+            appFile.write(render_application(appName))
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(usage="Export application(s) to rst file")

Documentation/Cookbook/Scripts/otb_warnings.py

+import sys
+
+def parameter_warnings(app_warn, app, key):
+
+    def warn(message):
+        app_warn("Parameter '{}' ".format(key) + message)
+
+    name = app.GetParameterName(key)
+    description = app.GetParameterDescription(key)
+
+    if name[-1] == " ":
+        warn("name ends with a space")
+
+    if ":" in name:
+        warn("name contains special character (:)")
+
+    if "." in name:
+        warn("name contains special character (.)")
+
+    #if description == "":
+        #warn("missing description")
+
+    #if len(description) > 0 and description[-1] != ".":
+        #warn("description does not end with a period")
+
+    if len(description) > 0 and " :" in description:
+        warn("description has a space before a colon")
+
+def application_documentation_warnings(app):
+    "Emit warnings about application documentation"
+
+    def warn(message):
+        print("OTB Documentation Warning ({}): {}".format(app.GetName(), message), file=sys.stderr)
+
+    description = app.GetDescription()
+    longdescription = app.GetDocLongDescription()
+
+    if not longdescription[-1] == ".":
+        warn("Application Long Description does not end with a period (.)")
+
+    if " :" in longdescription:
+        warn("Application Long Description has a space before a colon")
+
+    if app.GetNumberOfExamples() == 0:
+        warn("Application has no examples")
+
+    keys = app.GetParametersKeys()
+    for key in app.GetParametersKeys():
+        parameter_warnings(warn, app, key)
+
+    if "ram" in keys and not keys[-3] == "ram":
+        warn("'ram' parameter is not third from last")
+
+    if "inxml" in keys and not keys[-2] == "inxml":
+        warn("'inxml' parameter is not second from last parameter")
+
+    if "outxml" in keys and not keys[-1] == "outxml":
+        warn("'outxml' is not last parameter")
+