2013-02-09

Using Markdown to generate reports and documentation

Markdown is a hit on the internet. It's being supported by more and more platforms, it started for me with Stackoverflow and later on my favourite project hosting website (Bitbucket) made it their default Wiki markup language.

And I like Markdown, it's syntax is quite simple, you can read the document and get a feel for it's structure (emphasize, headings, lists) without a conversion to HTML. But it had a thing missing, a LabVIEW Markdown generator.
And it bugged me.
So I created a project (a while ago) in LabVIEW, and just the last week I took the time to finish the project.
It's now a Class that overrides the LabVIEW Report Generation VIs, you can use your existing 'write to HTML/DOC/XLS' code to write a Markdown report.

It's not a full override of the Report Generation toolkit VIs, some functionality is not available in Markdown (margins) or in the toolkit's generic VIs (headings).

You can download the package from Bitbucket, and file your feature requests or bugs there as well.

Now what to do with this tool?
Well I wrote a simple VI that took some pre-written Markdown, added information about the toolkit, and pushed the information into the Bitbucket wiki. So the documentation of the toolkit is using the toolkit.
A screenshot of this VI is this:
As you can see, the only special from a normal report is that we instantiate a Markdown class that we upcast to a generic Report class. And the we use normal report functions (add text, add image) to generate valid Markdown.
Sometimes it takes some tweaking to get the result you want, adding extra linefeeds after/before an image is sometimes necessary (and can vary depending on your MD to HTML converter).

Please spread the word about Markdown, and the report toolkit, post your findings here. Add feature requests and bugs to the Bitbucket repo.

PS Markdown even got a semi-official logo [M↓]


PPS The report generation VIs are a mess. Please NI start over from scratch.

No comments:

Post a Comment