Merge pull request #418 from MRtrix3/script_doc

Enable auto-documentation of scripts

Author: Lestropie

scripts/act_anat_prepare_freesurfer

@@ -25,6 +25,7 @@ from lib.errorMessage import errorMessage
 from lib.printMessage import printMessage
 from lib.runCommand   import runCommand
 
+lib.app.author = 'Robert E. Smith (robert.smith@florey.edu.au)'
 lib.app.initCitations([ 'ACT' ])
 lib.app.initParser('Generate a 5TT image suitable for ACT from a FreeSurfer segmentation')
 lib.app.parser.add_argument('input',  help='The input image series; this should be one of the \'aseg\' images provided by FreeSurfer')

scripts/act_anat_prepare_fsl

@@ -16,6 +16,7 @@ from lib.printMessage import printMessage
 from lib.runCommand   import runCommand
 from lib.warnMessage  import warnMessage
 
+lib.app.author = 'Robert E. Smith (robert.smith@florey.edu.au)'
 lib.app.initCitations([ 'ACT', 'bet', 'fast', 'first', 'FSL' ])
 lib.app.initParser('Generate a 5TT image suitable for ACT from a T1 image using FSL tools')
 lib.app.parser.add_argument('input',  help='The input T1 image')

scripts/dwibiascorrect

@@ -13,6 +13,7 @@ from lib.getFSLSuffix  import getFSLSuffix
 from lib.getHeaderInfo import getHeaderInfo
 from lib.runCommand    import runCommand
 
+lib.app.author = 'Robert E. Smith (robert.smith@florey.edu.au)'
 lib.app.initCitations([ 'fast', 'FSL' ])
 lib.app.initParser('Perform B1 field inhomogeneity correction for a DWI volume series')
 lib.app.parser.add_argument('input',  help='The input image series to be corrected')

scripts/fs_parc_replace_sgm_first

@@ -23,6 +23,7 @@ from lib.errorMessage import errorMessage
 from lib.printMessage import printMessage
 from lib.runCommand   import runCommand
 
+lib.app.author = 'Robert E. Smith (robert.smith@florey.edu.au)'
 lib.app.initCitations([ 'first', 'FSL', 'SIFT_followup' ])
 lib.app.initParser('In a FreeSurfer parcellation image, replace the sub-cortical grey matter structure delineations using FSL FIRST')
 lib.app.parser.add_argument('parc',   help='The input FreeSurfer parcellation image')

scripts/lib/app.py

@@ -4,14 +4,16 @@
 # * -verbose prints all commands and all command outputs
 
 args = ''
+author = 'No author specified'
 citationWarning = ''
 cleanup = True
-epilog = ''
 lastFile = ''
 mrtrixQuiet = '-quiet'
 mrtrixNThreads = ''
 numArgs = 0
 parser = ''
+refList = ''
+standardOptions = ''
 tempDir = ''
 verbosity = 1
 workingDir = ''
@@ -37,16 +39,16 @@ def error(self, message):
 def initCitations(cmdlist):
 
   import lib.citations
-  global epilog, citationWarning
+  global refList, citationWarning
   max_level = 0
   for name in cmdlist:
     entry = [item for item in lib.citations.list if item[0] == name][0]
     if entry:
       max_level = max(max_level, entry[1]);
       # Construct string containing all relevant citations that will be fed to the argument parser epilog
-      if not epilog:
-        epilog = 'Relevant citations for tools / algorithms used in this script:\n\n'
-      epilog += entry[0] + ':\n' + entry[2] + '\n\n'
+      if refList:
+        refList += '\n'
+      refList += entry[0] + ': ' + entry[2] + '\n'
 
   if max_level:
     citationWarning += 'Note that this script makes use of commands / algorithms that have relevant articles for citation'
@@ -59,14 +61,18 @@ def initCitations(cmdlist):
 
 def initParser(desc):
   import argparse
-  global epilog, parser
+  global parser, refList, standardOptions
+  epilog = ''
+  if refList:
+    epilog = 'Relevant citations for tools / algorithms used in this script:\n\n' + refList + '\n'
+  epilog += 'Author:\n' + author + '\n\nCopyright (C) 2008 Brain Research Institute, Melbourne, Australia. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n'
   parser = Parser(description=desc, epilog=epilog, formatter_class=argparse.RawDescriptionHelpFormatter)
-  standard_options = parser.add_argument_group('standard options')
-  standard_options.add_argument('-continue', nargs=2, dest='cont', metavar=('<TempDir>', '<LastFile>'), help='Continue the script from a previous execution; must provide the temporary directory path, and the name of the last successfully-generated file')
-  standard_options.add_argument('-nocleanup', action='store_true', help='Do not delete temporary directory at script completion')
-  standard_options.add_argument('-nthreads', metavar='number', help='Use this number of threads in MRtrix multi-threaded applications (0 disables multi-threading)')
-  standard_options.add_argument('-tempdir', metavar='/path/to/tmp/', help='Manually specify the path in which to generate the temporary directory')
-  verbosity_group = standard_options.add_mutually_exclusive_group()
+  standardOptions = parser.add_argument_group('standard options')
+  standardOptions.add_argument('-continue', nargs=2, dest='cont', metavar=('<TempDir>', '<LastFile>'), help='Continue the script from a previous execution; must provide the temporary directory path, and the name of the last successfully-generated file')
+  standardOptions.add_argument('-nocleanup', action='store_true', help='Do not delete temporary directory at script completion')
+  standardOptions.add_argument('-nthreads', metavar='number', help='Use this number of threads in MRtrix multi-threaded applications (0 disables multi-threading)')
+  standardOptions.add_argument('-tempdir', metavar='/path/to/tmp/', help='Manually specify the path in which to generate the temporary directory')
+  verbosity_group = standardOptions.add_mutually_exclusive_group()
   verbosity_group.add_argument('-quiet',   action='store_true', help='Suppress all console output during script execution')
   verbosity_group.add_argument('-verbose', action='store_true', help='Display additional information for every command invoked')
 
@@ -75,9 +81,15 @@ def initParser(desc):
 def initialise():
   import argparse, os, random, string, sys
   from lib.printMessage          import printMessage
+  from lib.printUsageMarkdown    import printUsageMarkdown
   from lib.readMRtrixConfSetting import readMRtrixConfSetting
-  global args, cleanup, lastFile, mrtrixNThreads, mrtrixQuiet, tempDir, verbosity, workingDir
+  global args, author, cleanup, lastFile, mrtrixNThreads, mrtrixQuiet, standardOptions, parser, refList, tempDir, verbosity, workingDir
   global colourClear, colourConsole, colourError, colourPrint, colourWarn
+  
+  if len(sys.argv) == 2 and sys.argv[1] == '__print_usage_markdown__':
+    printUsageMarkdown(parser, standardOptions, refList, author)
+    exit(0)
+  
   workingDir = os.getcwd()
   args = parser.parse_args()
 

scripts/lib/printUsageMarkdown.py

@@ -0,0 +1,84 @@
+def printUsageMarkdown (args, stdopts, refs, author):
+  import argparse, os, sys
+  
+  argument_list = [ ]
+  for arg in args._positionals._group_actions:
+    argument_list.append(arg.dest)
+  
+  standard_option_list = [ ]
+  for opt in stdopts._group_actions:
+    standard_option_list.append(opt.option_strings[0])
+    
+  help_option = ''
+  option_list = [ ]
+  for opt in args._actions:
+    if opt.option_strings and not opt.option_strings[0] in argument_list and not opt.option_strings[0] in standard_option_list:
+      if opt.option_strings[0] == '-h':
+        help_option = opt
+      else:
+        option_list.append(opt.option_strings[0])
+  
+  print ('## Synopsis')
+  print ('')
+  print ('    ' + args.prog + ' [ options ] ' + ' '.join(argument_list))
+  print ('')
+  
+  for arg in args._positionals._group_actions:
+    _printArgument(arg)
+  
+  print ('')
+  print ('## Description')
+  print ('')
+  print (vars(args)['description'])
+  print ('')
+  
+  if option_list:
+    print ('## Options')
+    print ('')
+  
+    for opt in args._actions:
+      if opt.option_strings and opt.option_strings[0] in option_list:
+        _printOption(opt)
+        print ('')
+  
+  print ('#### Standard options')
+  print ('')
+  
+  _printOption(help_option)
+  print ('')
+  
+  for opt in stdopts._group_actions:
+    _printOption(opt)
+    print ('')
+      
+  print ('#### References')
+  print ('')
+  print (refs)
+  print ('')
+  print ('---')
+  print ('')
+  print ('**Author:** ' + author)
+  print ('')
+  print ('**Copyright:** Copyright (C) 2008 Brain Research Institute, Melbourne, Australia. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.')
+  
+  
+  
+  
+def _printArgument(arg):
+  print ('- *' + arg.dest + '*: ' + arg.help)
+  
+  
+  
+def _printOption(opt):
+  usage = ''
+  if len(opt.option_strings) == 1:
+    usage = [ opt.option_strings[0] ]
+  else:
+    usage = [ '[ ' + ' '.join(opt.option_strings) + ' ]' ]
+  if type(opt.metavar) is tuple:
+    for arg in opt.metavar:
+      usage.append(arg)
+  elif type(opt.metavar) is str:
+    usage.append(opt.metavar)
+  print ('+ **' + ' '.join(usage) + '**<br>' + opt.help)
+  

scripts/revpe_distcorr

@@ -26,6 +26,7 @@ from lib.printMessage  import printMessage
 from lib.runCommand    import runCommand
 from lib.warnMessage   import warnMessage
 
+lib.app.author = 'Robert E. Smith (robert.smith@florey.edu.au)'
 lib.app.initCitations([ 'eddy/topup', 'FSL' ])
 lib.app.initParser('Perform EPI distortion correction of a volume series using a reversed phase-encode image pair to estimate the inhomogeneity field')
 lib.app.parser.add_argument('pe_axis',   help='The phase encode direction / axis; can be an axis number (0, 1 or 2) or a code (e.g. AP, LR, IS)')

scripts/revpe_dwicombine

@@ -32,6 +32,7 @@ from lib.printMessage  import printMessage
 from lib.runCommand    import runCommand
 from lib.warnMessage   import warnMessage
 
+lib.app.author = 'Robert E. Smith (robert.smith@florey.edu.au)'
 lib.app.initCitations([ 'eddy/topup', 'FSL', 'Skare2010' ])
 lib.app.initParser('Perform EPI distortion & recombination of a pair of image volumes, where the diffusion gradient table is identical between the two series, but the phase-encode direction is reversed')
 lib.app.parser.add_argument('pe_axis', help='The phase encode direction / axis; can be an axis number (0, 1 or 2) or a code (e.g. AP, LR, IS)')

update_doc

@@ -34,6 +34,8 @@ folder=$(mktemp -d)
 
   rm -rf mrtrix3.wiki/commands/list
   mkdir -p mrtrix3.wiki/commands/list
+  rm -rf mrtrix3.wiki/scripts/list
+  mkdir -p mrtrix3.wiki/scripts/list
 
   echo '[[Home]]
 
@@ -47,13 +49,23 @@ folder=$(mktemp -d)
     echo '[['$(basename $n)']]<br>' >> mrtrix3.wiki/commands/_Sidebar.md
   done
 
+  echo '[[Home]]
+
+**Scripts**<br>
+' >> mrtrix3.wiki/scripts/_Sidebar.md
+
+  for n in `find mrtrix3/scripts/ -type f -print0 | xargs -0 grep -l "lib.app.initParser"`; do
+    $n __print_usage_markdown__ > mrtrix3.wiki/scripts/list/$(basename $n).md
+    echo '[['$(basename $n)']]<br>' >> mrtrix3.wiki/scripts/_Sidebar.md
+  done
+
   grep -rn --include=\*.h --include=\*.cpp '^\s*//CONF\b ' mrtrix3 | sed -ne 's/^.*CONF \(.*\)/\1/p' | ./format_config_options > mrtrix3.wiki/DesignPrinciples/List-of-configuration-file-options.md
 
 
   (
     cd mrtrix3.wiki
-    git add commands DesignPrinciples/List-of-configuration-file-options.md
-    git commit -m "automatic update of command documentation"
+    git add commands scripts DesignPrinciples/List-of-configuration-file-options.md
+    git commit -m "automatic update of command and script documentation"
     git push
   )