- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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:
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
@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.
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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)
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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?
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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.
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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/.
Next up: Troy Martin Hughes presents Calling Open-Source Python Functions within SAS PROC FCMP: A Google Maps API Geocoding Adventure on Wednesday April 23.
Register now at https://www.basug.org/events.
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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.
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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.
- Mark as New
- Bookmark
- Subscribe
- Mute
- RSS Feed
- Permalink
- Report Inappropriate Content
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