自动为宏构建文档

Question

我想为 collection 个 SAS 宏构建文档 pdf（或 html）。是否有我可以遵循的规范（或推荐）工作流程？

我正在考虑使用 R 和 Regex 导出我所有的宏并提取标题、描述、示例、变量描述和代码，然后使用 markdown 构建一个漂亮的布局out pdf 每当我添加宏或更改描述或示例时，我都可以通过几个步骤进行更新（我想不惜一切代价避免 copy/paste）。

虽然这会非常乏味和不灵活，但我可能会重新发明轮子。

我的宏都是这样的：

*--------------------------------------------------------;
* 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;

我的 collection 宏越来越多我想尽可能地尊重良好的做法，但我无法在 SAS 中找到很多与良好文档相关的信息。

@Allan-Bowe 给出了一个很好的答案，这可能是最佳实践，但不幸的是我无法从我的工作计算机上安装 doxygen，所以我正在寻找其他不需要的解决方案外部软件。

Answer 1

不需要 re-invent 轮子 - 一个很好的文档方法是 doxygen。

我们将其用于开源 SASjs Macro Core library（其中还列出了很多 SAS 宏开发的良好实践）。

只需在 header 中定义您的属性（接受降价），例如：

/**
  @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

**/

然后只需将 doxygen 指向您的源文件夹，告诉它要使用哪个配置文件（对 SAS 来说一个好的配置文件是 here），然后为您的文档选择一个输出目录。

它看起来像 this。

没有 pdf 选项，但它可以创建可用于生成 pdf 的 DOCBOOK 格式的文件：http://www.doxygen.nl/manual/config.html#config_docbook

更新 - 我们最近为 SASjs 添加了 doxygen 支持 - 使用一个命令 (sasjs doc) 你可以记录你所有的工作，甚至生成一个 graphviz 数据沿袭图，集成到输出中.

概览：https://www.youtube.com/watch?v=ESNdCtXKRrw

Answer 2

您似乎已经将参数定义放在不同的行中。这应该有助于解析源文件。还要将宏名称添加到 %MEND 语句中，以便您的解析代码可以仔细检查它没有找到错误的。

我还建议将您的评论块移动到宏中。

%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;

自动为宏构建文档

build documentation automatically for macros

documentation

sas