rpp/blocks/rpp_update_doc.m

   1 % Copyright (C) 2013-2015 Czech Technical University in Prague
   2 %
   3 % Authors:
   4 %     - Carlos Jenkins <carlos@jenkins.co.cr>
   5 %     - Michal Sojka <sojkam1@fel.cvut.cz>
   6 %
   7 % Permission is hereby granted, free of charge, to any person
   8 % obtaining a copy of this software and associated documentation
   9 % files (the "Software"), to deal in the Software without
  10 % restriction, including without limitation the rights to use,
  11 % copy, modify, merge, publish, distribute, sublicense, and/or sell
  12 % copies of the Software, and to permit persons to whom the
  13 % Software is furnished to do so, subject to the following
  14 % conditions:
  15
  16 % The above copyright notice and this permission notice shall be
  17 % included in all copies or substantial portions of the Software.
  18
  19 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  20 % EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  21 % OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  22 % NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  23 % HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  24 % WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  25 % FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  26 % OTHER DEALINGS IN THE SOFTWARE.
  27 %
  28 % File : compile_blocks.m
  29 % Abstract:
  30 %     Compile all the C-MEX S-Function in current folder.
  31 %
  32 % References:
  33 %     http://www.mathworks.com/help/matlab/ref/mex.html
  34 %     http://www.mathworks.com/help/matlab/matlab_external/custom-building-mex-files.html
  35
  36 function updated = rpp_update_doc(varargin)
  37 % RPP_UPDATE_DOC Update built-in S-functions documentation.
  38 %    The documentation is updated based on the YAML comment in .c files.
  39 %    The number of updated blocks is returned.
  40 if nargin > 0,
  41     op = varargin{1};
  42 else
  43     op = 'update';
  44 end
  45 block_libs = rpp_get_blocks();
  46 updated = 0;
  47 for i=1:length(block_libs),
  48     block_lib = block_libs{i};
  49     last_updated = updated;
  50     load_system(block_lib);
  51     set_param(block_lib, 'Lock', 'off');
  52     blocks = find_system(block_lib, 'Type', 'block');
  53     for j=1:length(blocks),
  54         block = blocks{j};
  55         params = get_param(block, 'ObjectParameters');
  56         fields = fieldnames(params);
  57
  58         disp(['Processing ' blocks{j}]);
  59         updated = updated + process_param(op, block, 'MaskType', '--masktype');
  60         updated = updated + process_param(op, block, 'MaskDescription', '--html --printdesc');
  61         updated = updated + process_param(op, block, 'MaskPromptString', '--maskpromptstring');
  62         updated = updated + process_param(op, block, 'MaskHelp', '--html --printhelp');
  63         updated = updated + process_param(op, block, 'Name', '--name'); % Name must be changed last!!!
  64     end
  65     set_param(block_lib, 'Lock', 'on');
  66     if strcmp(op, 'update') && updated ~= last_updated,
  67         save_system(block_lib);
  68     end
  69     close_system(block_lib);
  70 end
  71
  72 function output = run_doc_parse(fn, opts)
  73     % We have to unset Matlab's library path in order to run pandoc - it
  74     % needs newer libc than the one shipped with Matlab
  75     [rc, output] = system(['unset LD_LIBRARY_PATH; scripts/doc_parse.py ' opts ' ' fn '.c']);
  76     if rc ~= 0,
  77         disp(output)
  78         throw(MException('rpp:pandoc_failure', ['Failed to extract doc from ' fn '.c']))
  79     end
  80
  81 function print_diff(fn, param, old, new, diffopts)
  82     fnold = [fn '.' param '.old'];
  83     f = fopen(fnold, 'w');
  84     fprintf(f, '%s', old);
  85     fclose(f);
  86
  87     fnnew = [fn '.' param '.new'];
  88     f = fopen(fnnew, 'w');
  89     fprintf(f, '%s', new);
  90     fclose(f);
  91
  92     [rc, diff] = system(['git --no-pager diff --no-index ' diffopts ' --word-diff=plain ' fnold ' ' fnnew]);
  93     disp(diff);
  94     delete(fnold);
  95     delete(fnnew);
  96
  97 function updated = process_param(op, block, param, opts)
  98     fn = get_param(block, 'FunctionName');
  99     new_content = run_doc_parse(fn, opts);
 100     old_content = get_param(block, param);
 101
 102     if strcmp(param, 'MaskType') || ...
 103        strcmp(param, 'MaskPromptString') || ...
 104        strcmp(param, 'Name'),
 105         new_content = deblank(new_content);
 106     end
 107
 108     if ~strcmp(old_content, new_content),
 109         if strcmp(op, 'diff'),
 110             disp([block ': ' param ' not up-to-date'])
 111             print_diff(fn, param, old_content, new_content, '')
 112         else
 113             set_param(block, param, new_content)
 114             print_diff(fn, param, old_content, new_content, '--no-color')
 115         end
 116         updated = 1;
 117     else
 118         updated = 0;
 119     end