The API documentation for FPAssistant Suite SDK is available on the web at the following URL: http://api.fpassistant.com/ This contains documentation for developers as well as articles to assist in using the product.
API Documentation Website
A few people have recently asked ‘how this is produced?‘, being developers we like to make it easy and automatic! In essence we just document the source code as we program using a comment syntax which contains XML text and then execute a pipeline in Azure DevOps which will call DocFX to create the static documentation which is then uploaded to a website hosted on Azure as a App Service; just a couple of mouse clicks!!
Let’s look at whats involved in a little more detail…
Source Code Comments
The key is to document your source code using a predefined set of XML element tags which the documentation system will read. In the example below we can see XML tag elements like <summary> <param name> <returns> and <remarks>. There are others and a full list and further details are here.
Source Code Comments
This above source (lines 422-432) will be processed and documented like this on the website…
MOC/VEB Calculation Method
Creating the Documentation – DocFX Tool
Namespace Documentation
Class Documentation for Developers
The images above show screen captures of part of the documentation for Namespace and a Class (PBN RNP AR). We use a tool from Microsoft called DocFX which will parse the source code and create the static documentation based on a set of rules. DocFX is a really powerful tool and allows us to embed the rules within out Visual Studio project. We can also add further documentation like articles with the ability to create a new template for the final website. There are other source code documentation packages and we only have knowledge of DocFX.
Azure DevOps – CD/CI Pipeline
The magic happens in Azure DevOps, as the source code is hosted here where a simple pipeline has been written that simply copies the source code (along with the DocFX rules) and then tells DocFX to do its work. Once this is done and the static documentation is created, this is then deployed to the Azure App Service so that it’s available on the WWW for all to view.
Azure DevOps DocFx Pipeline
More Details…
If you have any questions or would like more information about the process then please do make contact.
