BookmarkSubscribeRSS Feed
AllanBowe
Barite | Level 11

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:

 

/Allan
SAS Challenges - SASensei
MacroCore library for app developers
SAS networking events (BeLux, Germany, UK&I)

Data Workflows, Data Contracts, Data Lineage, Drag & drop excel EUCs to SAS 9 & Viya - Data Controller
DevOps and AppDev on SAS 9 / Viya / Base SAS - SASjs
13 REPLIES 13
Ron_MacroMaven
Lapis Lazuli | Level 10

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.

 

http://latex.org/forum/

 

and the package fancyvrb.

 

https://ctan.org/pkg/fancyvrb

 

Ron Fehd  doc maven

 

AllanBowe
Barite | Level 11

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

/Allan
SAS Challenges - SASensei
MacroCore library for app developers
SAS networking events (BeLux, Germany, UK&I)

Data Workflows, Data Contracts, Data Lineage, Drag & drop excel EUCs to SAS 9 & Viya - Data Controller
DevOps and AppDev on SAS 9 / Viya / Base SAS - SASjs
Tom
Super User Tom
Super User

@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.

 

 

AllanBowe
Barite | Level 11

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)

/Allan
SAS Challenges - SASensei
MacroCore library for app developers
SAS networking events (BeLux, Germany, UK&I)

Data Workflows, Data Contracts, Data Lineage, Drag & drop excel EUCs to SAS 9 & Viya - Data Controller
DevOps and AppDev on SAS 9 / Viya / Base SAS - SASjs
jriveralo77
Calcite | Level 5

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?

AllanBowe
Barite | Level 11
afraid not - here's an unanswered SO post on the topic: https://stackoverflow.com/questions/51966304/remove-file-tags-from-doxygen-output
/Allan
SAS Challenges - SASensei
MacroCore library for app developers
SAS networking events (BeLux, Germany, UK&I)

Data Workflows, Data Contracts, Data Lineage, Drag & drop excel EUCs to SAS 9 & Viya - Data Controller
DevOps and AppDev on SAS 9 / Viya / Base SAS - SASjs
NicoM
Obsidian | Level 7

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.

KTWiggins
Fluorite | Level 6
Hi! I was wondering the same thing - is doxygen still working for OP, or is there another tool / learned practices sources that might have come along? Thanks for any help! Been online for faaar too long trying to research 🙂
Quentin
Super User

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/.

BASUG is hosting free webinars Next up: Don Henderson presenting on using hash functions (not hash tables!) to segment data on June 12. Register now at the Boston Area SAS Users Group event page: https://www.basug.org/events.
KTWiggins
Fluorite | Level 6
I've been mired in that site and it looks fantastic - what about for documenting more than macros - like a tool that documents code input / output - I'm really new to automated documentation so I hope that doesn't sound too stupid...
NicoM
Obsidian | Level 7
Those kind of tools definitely exist for other programming languages. Doxygen does this for C++, C#, Python, Java and other languages. Unfortunately, SAS is not officially supported by Doxygen.

That still makes it useful to add headings to your SAS files though, but it does not parse the code itself. As far as I know such a tool does not exist for SAS code.
Patrick
Opal | Level 21

@KTWiggins 

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. 

AllanBowe
Barite | Level 11

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:  


Whilst Doxygen is great for code documentation, it's not so user friendly for user guides / admin guides etc.  For these, we are now standardising on docsify.  Here is our template repo (which we embed directly into the public folder of customer SAS web apps before customisation):  https://github.com/sasjs/docs

 

In the past we have used mkdocs, which powers the following sites:

 

* https://docs.datacontroller.io
* https://cli.sasjs.io
* https://sasjs.io

 

 

 

 

/Allan
SAS Challenges - SASensei
MacroCore library for app developers
SAS networking events (BeLux, Germany, UK&I)

Data Workflows, Data Contracts, Data Lineage, Drag & drop excel EUCs to SAS 9 & Viya - Data Controller
DevOps and AppDev on SAS 9 / Viya / Base SAS - SASjs

sas-innovate-2024.png

Available on demand!

Missed SAS Innovate Las Vegas? Watch all the action for free! View the keynotes, general sessions and 22 breakouts on demand.

 

Register now!

How to Concatenate Values

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.

Click image to register for webinarClick image to register for webinar

Classroom Training Available!

Select SAS Training centers are offering in-person courses. View upcoming courses for:

View all other training opportunities.

Discussion stats
  • 13 replies
  • 4134 views
  • 3 likes
  • 8 in conversation