I always wanted my API documentation to be always in sync with my development. One cool way to achieve this is to keep adding comments and headers while writing code. I loved the famous Doxygen tool that generates documentation from these comments. VSTS being a great ALM platform and Doxygen being a great documentation tool, I wanted to integrate them both and get the benefit out of having always up-to-date documentation that can be viewed directly in your VSTS project.
What it does
Its a VSTS extension which mainly contains two parts:
- A Build task to generate documentation as part of Build
- A Documentation hub under Code hub group to render the documentation from the selected Build.
How I built it
I have written a new Build task that runs Doxygen tool on latest code and generates Latex. Then the task runs PdfLatex to generate a PDF file out of the Latex. This PDF file is then uploaded as an artifact in the Build.
I have written a Documentation hub under Code hub group, where I have written the code to download this artifact based on selected build and then load the pdf file under the documentation hub.
Challenges I ran into
Downloading the artifact zip and rendering the pdf under the Documentation hub was the major challenge. It works good in Google Chrome but somehow rendering of pdf is not happening successfully in Internet Explorer and Microsoft Edge.
Accomplishments that I'm proud of
I am proud that I am successful in integrating these two awesome products and my solution will make life easier for developers. They can now refer to the most up-to-date API documentation directly on VSTS and will not have to do code searches to know more about some API.
What I learned
I learned working with node.js, zip.js and concepts of blobs and ArrayBuffers.
What's next for Documentation via Doxygen in VSTS
Currently, the documentation is shown in PDF format, I am planning to take the project further to add support for Markdown files as well.