Recommended documentation tool for SAS code

[AllanBowe]

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:

• CodeDoc 
• DocItOut
• JavaDoc

[Ron_MacroMaven]

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]

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

[Tom]

---

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

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)

[jriveralo77]

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]

afraid not - here's an unanswered SO post on the topic: https://stackoverflow.com/questions/51966304/remove-file-tags-from-doxygen-output

[NicoM]

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]

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]

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

[KTWiggins]

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]

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]

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

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