VCF Operations Orchestrator: Auto-Document Your Actions with Ease

I spend a significant amount of time developing code for VCF Operations Orchestrator, and while I follow a strict and structured development process, documentation often falls behind. Keeping documentation up to date is an ongoing challenge as it’s difficult to maintain and keep up with frequent code changes.

To solve this, I decided it was time to automate the documentation process and created a script to achieve this. When I set out to build this solution, I had a clear set of requirements I wanted it to meet:

• Generate markdown (.md) files that are compatible with GitLab/GitHub/Azure Devops Wiki
• Act as an extension to the Build Tools for VMware Aria;
• Use NodeJS, as this would already be available when using Build Tools for VMware Aria;
• Require little or no dependencies;
• Able to read and process checked-out source code;
• Handle standard Actions, Class wrapper Actions, prototypes and inline methods;
• Support JSDoc tags;
• Honours the module hierarchy (use the same hierarchy for documents);

You can find my documentation tool here: vcf-operations-orchestrator-doc-generator, along with instructions on how to use the script. Please note that you must be managing your code using the Build Tools for VMware Aria using a JS-Based Actions-Only Project.

The documentation tool provides the following features:

• Documents Actions that are used as Class wrappers
• Documents standard Actions and creates a single document based on the parent directory
• Adds the module path
• For Classes, detects inheritance (extends)
• Documents all functions (prototype-based and inline)
• Documents all parameters and returns
• Preserves examples and displays them in JavaScript highlighting
• Outputs in Markdown (md) files
• Creates a root-level README linking to all sub-pages
• Documentation folder structure honours the code hierarchy
• Easily integrated into a pipeline and pushed to supporting systems such as Azure DevOps Wiki

If you’re not using the Build Tools, Mayank Goyal has created a tool called VRODoc that can connect to Orchestrator and document Actions in a package.

If you want to document your Workflows, Josh Broadway also has a tool, vcf-automation-orchestrator-automated-workflow-documentation.

Example documents that are created:

Class Document

ActiveDirectoryService.md – A single file that documents a class and all methods.

Standard Action Document

vm.md – A single file to represent the module path “com.simplygeek.vcenter.vm” where all Actions within the module are presented as documented “functions”.

Top-Level README (TOC):

README.md – Top-level file that acts as a table of contents for all the produced files.

After many sleep-deprived nights, I now have a solution that generates documentation automatically, that I can seamlessly integrate into my pipeline and publish directly to my preferred wiki.

I hope that by sharing this solution, I can help others automate their documentation. As this is the initial release, there may be some issues, but I welcome your feedback and will do my best to support.

Please feel free to reach out with any questions or suggestions.