I'm starting a new project and I'd like to build the comment header of my macros in such a way that it can be imported into a documentation tool.
Does anyone have any recommendations? My review so far has surfaced:
Q.1: static or dynamic?
i.e. are you going to run this documentation-extraction program once,
or periodicly?
Q.2 output file type?
pdf? or html?
or xml?
Q.2: what are your begin and end markers for documentation?
in my programs, that's a single slash asterisk comment.
/* name: ..\SAS-site\macros\calltext.sas
description: ...
purpose: ...
....
****/
take a look through SAS example programs
and you'll see lots of /* ... */ on every single line of the header
"C:\Program Files\SASHome\SASFoundation\9.4\core\sasmacro\aarfm.sas"
/******************************************************************************/
/* Copyright (c) 2013 by SAS Institute Inc., Cary, NC USA 27513 */
/* */
/* NAME: aaRFM */
take a look at Michael Fiendly's pages
http://www.math.yorku.ca/SCS/friendly.html
I also recommend LaTeX for *.pdf.
I use typesetting system in all my papers.
and the package fancyvrb.
Ron Fehd doc maven
Hi Ron - thanks for following up!
In the end, I went with doxygen
Example code is available in our open source github library here: https://github.com/sasjs/core
Example (generated) documentation is here: https://core.sasjs.io
It's also used by the SASjs Dev Ops Framework, as part of the sasjs doc command (which can also generate data lineage if you specify your Data Inputs / Outputs)
/Allan
@AllanBowe wrote:
Hi Ron - thanks for following up!
In the end, I went with doxygen
Example code is available in our open source github library here: https://github.com/macropeople/macrocore
Example (generated) documentation is here: https://rawsas.github.io/coredoc/files.html
/Allan
Looks cool.
Could the doxygen header be AFTER the %MACRO statement? I don't like having source code for autocall macros that contain text that is not part of the macro.
Yes of course. There is extensive documentation on the documentation - http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
It's the best I've found for working with SAS, and credit for the idea should go to Rocco Cannizzaro (it's used to autogenerate documentation in the SAS IRM solution)
looking at the html, doxygen is creating some tags or definitions of the %macro calls and some words after the % . Do you know if there is a way to avoid that?
I stumbled upon this thread, and the related post in Stack Overflow, after I was trying to figure out whether doxygen is still the way to go for SAS code. I think you can avoid those unwanted definitions/tags by using the \cond and \endcond commands. See my answer on Stack Overflow.
Pretty sure @AllanBowe is still using doxygen and advocating for its use by others.
The doxygen-generated documentation for a macro library he linked to in the post from 2017 is still alive, and growing: https://core.sasjs.io/.
Doxygen is what SAS uses since years for the SAS Risk Platform and the related Risk Solution Content packs. It takes a bit of extra development effort to keep the doxygen headers in code up-to-date when customizing something - but it's worth the effort.
...and SAS R&D was "mean" enough to design for some portion of the headers also being of functional importance (for the IRM component of the SAS Risk Solution) so a developer MUST keep the header in sync with the code logic implemented or the code will actually not work correctly.
We recommend Doxygen. To make setup easier, the SASjs framework auto-generates the doxyfile according to the sasjsconfig.json project setup.
The docs are here: https://cli.sasjs.io/doc/
Doxygen also allows you to draw GRAPHS in doxy headers, as well as standard markdown tables, here's an example: https://core.sasjs.io/mp__stackdiffs_8sas.html
With the SASjs doxygen wrapper, you can also define inputs and outputs to generate a DATA LINEAGE graph. It does depend on manual config, but at least this way you can draw meaningful graphs. Here's an overview:
In the past we have used mkdocs, which powers the following sites:
* https://docs.datacontroller.io
* https://cli.sasjs.io
* https://sasjs.io
Are you ready for the spotlight? We're accepting content ideas for SAS Innovate 2025 to be held May 6-9 in Orlando, FL. The call is open until September 25. Read more here about why you should contribute and what is in it for you!
Learn how use the CAT functions in SAS to join values from multiple variables into a single value.
Find more tutorials on the SAS Users YouTube channel.