refs #6709. Adapt wiki_maker for usages.

Code/Mantid/Build/wiki_maker.py

@@ -34,33 +34,77 @@
 
 #======================================================================
 def get_wiki_description(algo, version):
+    tryUseDescriptionFromBinaries = True
+    return get_custom_wiki_section(algo, version, "*WIKI*", tryUseDescriptionFromBinaries)
+
+#======================================================================
+def get_wiki_usage(algo, version):
+    wiki_usage = get_custom_wiki_section(algo, version, "*WIKI_USAGE*")
+    if wiki_usage:
+        return (True, wiki_usage)
+    else:
+        wiki_no_sig_usage = get_custom_wiki_section(algo, version, "*WIKI_USAGE_NO_SIGNATURE*")
+        return (False, wiki_no_sig_usage)
+
+#======================================================================
+def get_custom_wiki_section(algo, version, tag, tryUseDescriptionFromBinaries=False):
     """ Extract the text between the *WIKI* tags in the .cpp file
     
     @param algo :: name of the algorithm
     @param version :: version, -1 for latest 
     """
+
     global mtd
+
+    desc = ""
     source = find_algo_file(algo, version)
-    if source == '':
-        alg =  createAlgorithm(algo, version)
+    if source == '' and tryUseDescriptionFromBinaries:
+        alg =  mtd.createAlgorithm(algo, version)
         print "Getting algorithm description from binaries."
         return alg.getWikiDescription()
+    elif source == '' and not tryUseDescriptionFromBinaries:
+        print "Warning: Cannot find source for algorithm"
+        return desc
     else:
         f = open(source,'r')
         lines = f.read().split('\n')
         print lines
         f.close()
-        n = 0
+
         print algo
-        while not lines[n].lstrip().startswith("/*WIKI*") and not lines[n].lstrip().startswith('"""*WIKI*'):
-            n += 1
-        desc = ""
-        n += 1
-        while not lines[n].lstrip().startswith("*WIKI*"):
-            desc += lines[n] + "\n"
-            n += 1
-        print "Getting algorithm description from source."
+        try:
+            # Start and end location markers.
+            start_tag_cpp = "/" + tag 
+            start_tag_python = '"""%s' % tag
+            end_tag_cpp = tag + "/"
+            end_tag_python = '%s"""' % tag
+
+            # Find the start and end lines for the wiki section in the source.
+            start_index = 0
+            end_index = 0
+            for line_index in range(0, len(lines)):
+                line = lines[line_index]
+                if line.lstrip().startswith(start_tag_cpp) or line.lstrip().startswith(start_tag_python):
+                    start_index = line_index + 1
+                    continue
+                if line.lstrip().startswith(end_tag_cpp) or line.lstrip().startswith(end_tag_python):
+                    end_index = line_index
+                    break
+
+            # Concatinate across the range.
+            for line_index in range(start_index, end_index):
+                desc += lines[line_index] + "\n"
+
+            if start_index == end_index:
+                print "No algorithm %s section in source." % tag
+            else:
+                print "Getting algorithm %s section from source." % tag
+
+        except IndexError:
+            print "No algorithm %s section in source." % tag
         return desc
+
+
 
 
 #======================================================================
@@ -198,10 +242,13 @@ def make_wiki(algo_name, version, latest_version):
 
     out += "== Summary ==\n\n"
     out += alg._ProxyObject__obj.getWikiSummary().replace("\n", " ") + "\n\n"
-
+    # Fetch the custom usage wiki section.
+    include_signature, custom_usage = get_wiki_usage(algo_name, version)
     out += "\n\n== Usage ==\n\n"
-    out += " " + create_function_signature(alg, algo_name) + "\n\n" 
+    if include_signature:
+        out += " " + create_function_signature(alg, algo_name) + "\n\n" 
     out += "<br clear=all>\n\n" 
+    out += custom_usage
     out += "== Properties ==\n\n"
 
     out += """{| border="1" cellpadding="5" cellspacing="0" 
@@ -227,11 +274,7 @@ def make_wiki(algo_name, version, latest_version):
 
     out += "== Description ==\n"
     out += "\n"
-    desc = ""
-    try:
-        desc = get_wiki_description(algo_name,version)
-    except IndexError:
-        pass
+    desc = get_wiki_description(algo_name,version)
     if (desc == ""):
       out += "INSERT FULL DESCRIPTION HERE\n"
       print "Warning: missing wiki description for %s! Placeholder inserted instead." % algo_name
@@ -359,7 +402,7 @@ def create_function_signature(alg, algo_name):
     prototype =  algo_name + _get_function_spec(_alg)
 
     # Replace every nth column with a newline.
-    nth = 4
+    nth = 3
     commacount = 0
     prototype_reformated = ""
     for char in prototype:
@@ -374,6 +417,7 @@ def create_function_signature(alg, algo_name):
 
     # Strip out the version.
     prototype_reformated = prototype_reformated.replace(",[Version]", "")
+    prototype_reformated = prototype_reformated.replace(",\n  [Version]", "")
 
     # Add the output properties
     props = alg._ProxyObject__obj.getProperties()