Example Code

Atlassian Confluence \ JIRA \ LabVIEW Class Auto-documentation APIs and Examples

Code and Documents

Third-Party Code Repository

Some users manage their code in repositories outside of ni.com. Use your best judgment when following links to third-party sites. https://bitbucket.org/ChrisCilino/labview-auto-documentation

Description

Author: Chris Cilino, CLA \ LabVIEW Champion, Center Of Excellence Technical Lead
NI Product(s) Used: LabVIEW
Industry: Semiconductor

The Challenge

To reduce the barrier to complete documentation by augmenting manually generated documentation in our Confluence wiki with automatically generated documentation for LabVIEW classes. Any documentation that's missing from classes should cause the generation of a JIRA ticket with detailed information about whats missing.

 

The Solution

I've created a scalable \ extenisble auto-documention API and an extensible set of Atlassian APIs (Confluence and JIRA) to automatically generate documentation for LabVIEW classes and host the report in a Confluence page. 

 

Introduction

One of the software engineering best practices is to clearly document the different facets of our classes, including

  1. Class Charter
  2. Class Location on disk
  3. Private Data information
  4. Member information

While this documentation can and does exist in the class itself, it's helpful to have a summarized report in a Confluence wiki, allowing anyone to view the capabilities of the classes in one, company wide accessible location without needing the LabVIEW IDE to view the class documentation. 

 

Filling in class documentation often times is only partially completed. Therefore I've also created a JIRA API that allows us to audit and create tickets clearly indicating what the problems are with the documentation. While the first application of the JIRA API is to file tickets for documentation, it is written in a completely generic way.

 

Application Description

 In order to maintain a separation of concerns, the APIs and the example applications are completely independent. Therefore the APIs controlling confluence and JIRA can be used in any other application.

 

I've also created an API to programmatically create reports. The report API (as well asl the other APIs) is object oriented. The first child of the API is to generate reports for LabVIEW classes. The API can be extended to any LabVIEW element supported by VI server such as, VIs, ctls, lvlibs, etc.  

 

The example programs I've included utilize very simple architectures. Both are "single shot", meaning the parameters (such as Confluence login credentials) are entered at edit time and then code is run without an event handler to service user input at runtime. 

 

The UML diagram below summarizes the relationship of the classes I've created.2019-04-05_11h00_47.png

The outer dotted boxes denote lvlibs. 

 

 

 

Impact/Results

 

Using the APIs and small applications included in the attached zip files, you can easily create reports in the format you see below:

Description

Image

A Confluence Class Report contains the Charter, Disk Location, Private Data Members, and Methods of a LabVIEW Class.

 

Private Data describes the name, description and data type of all private data of the class.

2018-07-20_15h50_26.png

Name describes the data structure of the data.

"{}" indicates a cluster. An element of a cluster is "{}.name" 

2018-07-20_15h50_48.png

LabVIEW Classes with their own documentation are automatically linked to their respective class documentation pages.

2018-12-20_15h27_46.png

"[]" indicates an array. An element of an array is "[].name".

 

2018-07-20_15h51_02.png
"*" indicates a reference. The element referred to is "[].name" 2018-07-20_15h51_09.png
Typedefs are described as "TypeDef "Name of .clt": Data type. If the .ctl is an enum the data type of the enum is reported and the {Value : Text} pairs 

2019-03-01_09h43_57.png

 The individual members of a class are listed in a table with detailed information.  2018-07-20_15h51_19.png
The JIRA API allows creation of tickets with the following form: 2018-07-20_15h54_36.png

 

Storing Documentation Locations in the Item being Documented

Each item (like class or project or VI) knows where it's documentation is located by virtue of tags. This is a little know way of associating metadata with LabVIEW files \ objects, like classes or projects or VIs or controls. You can access class tags using the following invoke nodes:

2018-12-20_15h33_39.png

 

I've designed a tagging system to tag the location of every report\printout combination. The system is

<G3GlobalTag>:-:G3AutoDocPrinterReportComboTag:-:<ReportClass>.lvclass::<PrinterClass>.lvclass

As an example:

G3Tag:-:G3AutoDocPrinterReportComboTag:-:G3_Documentation Reports.lvlib:Class Report.lvclass::G3_Documentation

Reports.lvlib:Confluence-JIRA.lvclass

 

As a result any combination of report \ printout is saved to the item (if the printer deems it important to do so). And each item can be asked for its documentation of a specific type. This is a scalable system to embed all locations of documentation in source. The VI most directly for saving the tags is

"user.lib\_Cirrus Logic\LabVIEW Auto Documentation\Source\Report\Abstract\APIs\Print.vi". In previous versions of this utility, the "Help tag" was used to store the information.

 

You'll need to edit your code in the following locations for the auto-generation utility to pick up the text

 

Item Being Documented Source of Information
Class Charter image2018-7-24_13-4-31.png
Private Data Name image2018-7-24_13-6-13.png
Private Data Description


image2018-7-24_13-6-49.png

 

image2018-7-24_13-7-26.png

 

Private Data Descriptions for Classes in DVRs

For private data members of classes in DVRs, copy the object out of the DVR, edit the class description, then drop it into the DVR.

2018-07-27_16h02_32.gif

Scope Setting Member Scope
Dynamic Dispatch Setting Dynamic Dispatch
Must Override Creating Member VIs
Must Override - Reason If any class member is marked as "Require descendant classes to override this dynamic dispatch VI" use the XML tag "<RequiredOverrideReason>[content]</RequiredOverrideReason>" in the VI's documentation. In this tag describe the reason for requiring an override.
Must Use Parent Creating Member VIs
Must Use Parent - Reason If any class member is marked as "Require overrides of this dynamic dispatch VI to always invoke the Call Parent Method node" use the XML tage "<MustCallParent>[content]</MustCallParent>" in the VI's documentation. In this tag describe the reason for requiring the method to call its parent.
Member Description Setting VI Descriptions

Conclusion

The APIs are in their infancy. However, even at this early stage, they provide a tremendous benefit to me and should also prove useful to the LabVIEW community at large.

 

Author Contact Details

My Champion's Profile

Example code from the Example Code Exchange in the NI Community is licensed with the MIT license.

Comments
Albert.Geven
Trusted Enthusiast Trusted Enthusiast
Trusted Enthusiast
on
Thanks Chris After my holidays I take a look.
greetings from the Netherlands
Paul-D
NI Employee (retired)
on

Thanks for sharing @Chris_Cilino!

Paul Davidson
National Instruments
Product Owner - ni.com Chat
richardscheff
Member
Member
on

Thank you.  I was wondering how the progress is going with project report.  It would be a huge benefit to many.  

Chris_Cilino
Active Participant Active Participant
Active Participant
on

@richardscheff,

You're welcome! I actually just released a new version yesterday. I've made some improvements and fixed a few bugs. Enjoy! And again, my thanks to @soliton for their contribution (https://www.solitontech.com/)

SriAtluri7
Member
Member
on

Great stuff, Chris! Is there a way to simply print to text/ PDF/ word file instead of publishing to Confluence/ JIRA?

t.kendall
Member
Member
on

Chris

 

I am wanting to use this and I was wondering if we could put it up on github or something so I can feed my changes back in for the community? 

 

Building in the 2FA stuff.

Chris_Cilino
Active Participant Active Participant
Active Participant
on

@SriAtluri7, While there isn't an implementation for txt / pdf / word file yet, those can be written by extending the printer class. I'm thinking about writing a printer to print to bitbucket for my new repository at https://bitbucket.org/ChrisCilino/labview-auto-documentation/src/master/. The repository is still a work in progress. I'm currently creating the wiki and designing the system by which the software and its dependencies can be downloaded. Ultimately I hope to use GCentral to distribute the software but it isn't quite up and running yet. The installation procedure (Under Construction ) contains the info to get the AutoDocumentation Utility.  

Chris_Cilino
Active Participant Active Participant
Active Participant
on
Contributors