build documentation automatically for macros - sas

Question

I want to build a documentation pdf (or html) for a collection of SAS macros. Is there a canonic (or recommended) workflow that I can follow ?
I'm thinking of exporting all my macros and extract title, description, examples, variable descriptions and code using R and Regex then use markdown to build a nicely laid out pdf that I can update in a few steps whenever I add a macro or change descriptions or examples (I want to avoid copy/paste at all cost).
It'd be quite tedious and unflexible though and I might be reinventing the wheel.
My macros all look like this:
*--------------------------------------------------------;
* ASSERT_EXIST ;
* Fails explicitely when a table doesn't exist ;
* Accepts a list of tables as input ;
*--------------------------------------------------------;
/* EXAMPLES
%assert_exist(not_a_table); * prints explicit error and aborts;
%assert_exist(sashelp.class); * does nothing;
%assert_exist(sashelp.cars not_a_table sashelp.class); * prints explicit error and aborts;
*/
%macro assert_exist
(data /* table or list of tables */
);
%local i table;
%do i=1 %to %sysfunc(countw(&data,%str( )));
%let table = %scan(&data,&i,%str( ));
%if not %sysfunc(exist(&table)) %then %do;
%put ERROR: Table &table doesnt exist!;
%abort;
%end;
%end;
%mend;
*----------------------------------------------;
* DROP ;
* Delete table or list of tables ;
* Default deletes all tables starting with _ ;
*----------------------------------------------;
/* EXAMPLES
data _x;
input char1 $ num1;
datalines;
a 1
b 2
;
%put %sysfunc(exist(_x)); * 1;
%drop(_x);
%put %sysfunc(exist(_x)); * 0;
*/
%macro drop
(data /* Name of table to drop, end name of table with ':' to delete all tables with this prefix */
);
%if &data= %then %let data = _:;
proc datasets nolist;
delete &data;
run;
%mend;
*--------------------------------------------------------;
* HEAD ;
* select top rows ;
*--------------------------------------------------------;
/* EXAMPLES
%head(sashelp.class,2) * keep only 2 first rows;
* %drop(_TEMP_); * clean up;
*/
%macro head
(data /* source table */
,n /* number of rows to keep */
,out /* output table */
);
/* default values, checks, initialisations */
%if &data= %then %let data = _TEMP_;
%if &out= %then %let out = _TEMP_;
%if &out=. %then %let out = &data;
%assert_exist(&data)
proc sql inobs=&n;
CREATE TABLE &out AS
SELECT *
FROM &data;
quit;
%mend;
My collection of macros is growing I'd like to respect good practice as much as possible but I've not been able to find much information relative to good documentation in SAS.
#Allan-Bowe gave a great answer which is probably the best practice, but unfortunately I have no way to install doxygen from my work computer, so I'm looking for other solutions not requiring external software.

Answer 1

No need to re-invent the wheel - a great approach for documentation is doxygen.
We use it for the open source SASjs Macro Core library (which also lists a lot of good practices for SAS Macro development).
Simply define your attributes in the header (markdown is accepted), eg:
/**
#file
#brief Logs a key value pair a control dataset
#details If the dataset does not exist, it is created. Usage:
%mp_setkeyvalue(someindex,22,type=N)
%mp_setkeyvalue(somenewindex,somevalue)
#param key Provide a key on which to perform the lookup
#param value Provide a value
#param type= either C or N will populate valc and valn respectively. C is
default.
#param libds= define the target table to hold the parameters
#version 9.2
#author Allan Bowe
#source https://github.com/sasjs/core
**/
Then simply point doxygen at your source folder, tell it which config file to use (a good one for SAS is here) and then choose an output directory for your documentation.
It'll look like this.
There's no pdf option, but it can create files in DOCBOOK format that can be used to generate a pdf: http://www.doxygen.nl/manual/config.html#config_docbook
UPDATE - we recently added doxygen support to SASjs - with a single command (sasjs doc) you can document all your jobs, and even generate a graphviz data lineage diagram, integrated into the output.
Overview: https://www.youtube.com/watch?v=ESNdCtXKRrw

Answer 2

You already seem to be placing the parameter definitions on separate lines. That should help with parsing the source files. Also add the macro name to the %MEND statement so that your parsing code can have a double check that it didn't find the wrong one.
I would also recommend moving your comment blocks into the macro.
%macro assert_exist
(data /* table or list of tables */
);
/*--------------------------------------------------------;
* ASSERT_EXIST ;
* Fails explicitely when a table doesn't exist ;
* Accepts a list of tables as input ;
*--------------------------------------------------------;
EXAMPLES
%assert_exist(not_a_table); * prints explicit error and aborts;
%assert_exist(sashelp.class); * does nothing;
%assert_exist(sashelp.cars not_a_table sashelp.class); * prints explicit error and aborts;
*/
%local i table;
%do i=1 %to %sysfunc(countw(&data,%str( )));
%let table = %scan(&data,&i,%str( ));
%if not %sysfunc(exist(&table)) %then %do;
%put ERROR: Table &table doesnt exist!;
%abort;
%end;
%end;
%mend assert_exist;