Tricks for documenting software

From BanghamLab
Jump to navigation Jump to search

Return

To enable section editing you need to turn it on in your preferences. You can do this by:

  1. log into the wiki, then click 'My preferences' at the very top of the screen.
  2. In the preferences section click on the 'Editing' tab.
  3. Tick 'Enable section editing via [edit] links', then click Save.

Transferring Matlab files, zipping toolboxes and dependencies

  • To include a Matlab .m file with the usual Matlab format colours - use
webify_interaction_function('mfilename.m')

It will output a new file ('mfilename.txt') in the current directory that contains all the Wiki tags. Paste it directly to this Wiki.

  • Projects are usually made downloadable from our Lab server:
/cmpdartsvr3/www/downloads/software

It is best to exactly copy an existing reference, e.g. Petals Sauret-Güeto et al 2013 (NOTE: cmpdartsvr1 links directly to cmpdartsvr3 which replaces it.)

  • Toolboxes have lots of dependencies (functions etc. on which it depends) it is, therefore, essential to include all the dependencies into the same zip file. To assist the Toolbag includes
function Dep_List=myDepFun(name,toolbox,all)
   % Dep_List=myDepFun(name,toolbox)
   % 
   % Tool for recursively finding what further functions a function depends on.
   % myDepFun then creates a subdirectory of the 'toolbox' directory and copies
   % all the 'external' functions that it finds into that directory.
   % It also puts a copy of the full results (.mat file) into that subdirectory.
   %
   % WARNING: if the function depends on classfiles (in a directory with a name beginning with @)
   % then please create a subdirectory within the directory 'toolbox' with the following form
   % 'NAME_Dependencies_outside_TOOLBOX' and copy the classfile directories and contents directly
   % into this new directory, e.g.
   % AAMToolbox_Dependencies_outside_ShapeModelToolbox
   %
   % (This is because 'depfun' does not recognise classfile types.)
   %   
   % name, name of function m file inside a toolbox (without the suffix)
   % toolbox, path and name of the toolbox in which the function resides and which would normally
   %          be expected to contain all the functions needed. Functions outside the toolbox
   %          are 'external' tools
   % all, default false and the final list excludes functions in the toolbox, 
   %           if true then all functions are listed and external files are not copied into a local directory
   % Dep_List, a list of all the external tools with their DArT_Toolshed paths
   %
   % Usage
   % list=myDepFun('AAMToolbox','C:\DArT_Toolshed\Toolboxes\ShapeModelToolbox')
   % 
   % WARNING
   % at present this does not check each filename to see whether there is an associated
   % compiled version, i.e. dll, mexx64 etc.
   % To add a check would be straightforward if there is always an associated .m file
   %
   % J. Andrew Bangham, 2012