topic Re: Recommended documentation tool for SAS code in SAS Programming

Re: Recommended documentation tool for SAS code

Ron_MacroMaven — Tue, 25 Jul 2017 16:25:02 GMT

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

Re: Recommended documentation tool for SAS code

AllanBowe — Wed, 14 Apr 2021 19:23:49 GMT

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

Re: Recommended documentation tool for SAS code

Tom — Tue, 25 Jul 2017 18:43:50 GMT

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

Re: Recommended documentation tool for SAS code

AllanBowe — Tue, 25 Jul 2017 22:40:08 GMT

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)

Re: Recommended documentation tool for SAS code

jriveralo77 — Wed, 12 Aug 2020 22:35:56 GMT

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?

Re: Recommended documentation tool for SAS code

AllanBowe — Thu, 13 Aug 2020 07:58:58 GMT

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

Re: Recommended documentation tool for SAS code

NicoM — Tue, 13 Oct 2020 11:46:06 GMT

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.

Re: Recommended documentation tool for SAS code

KTWiggins — Thu, 09 Jun 2022 17:38:04 GMT

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 🙂

Re: Recommended documentation tool for SAS code

Quentin — Thu, 09 Jun 2022 17:53:59 GMT

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

Re: Recommended documentation tool for SAS code

KTWiggins — Thu, 09 Jun 2022 18:26:44 GMT

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

Re: Recommended documentation tool for SAS code

NicoM — Fri, 10 Jun 2022 07:02:08 GMT

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.

Re: Recommended documentation tool for SAS code

Patrick — Fri, 10 Jun 2022 07:43:05 GMT

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

Re: Recommended documentation tool for SAS code

AllanBowe — Fri, 10 Jun 2022 09:29:32 GMT

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