In this post, Application Development Manager, Chris Mason discusses the challenge of keeping documentation up to date in this fast moving DevOps world. In addition, he spotlights DocFX and writes a build task extension which integrates it into your build pipeline.
Overview
We talk a lot about DevOps today and it represents a major strategy and focus for our developer platforms with Visual Studio Team Services (VSTS) and Team Foundation Server (TFS). There are plenty of examples out there covering various aspects of application deployments in a DevOps world: deploying apps, database migrations, and coded infrastructure. However, one area that seems to escape coverage is– documentation.
If we are deploying apps on a “cloud cadence” then we can expect new features to be rolling out to users every few weeks. When a user sees a new button, a new option, or a new color code in an app, they are going to want to know what it does. This means we need a rapid cadence to build and deploy new documentation so that when any new feature rolls out to the user, they can go and quickly find supporting information for it.
This idea is not earthshattering or new. Dynamic documentation generation has been around for ages, for example, the old Sandcastle project. While great for generating API level documentation for developers to look at, it is not necessarily the most user friendly result when done.
DocFx
Another option that is available today is the open-source option called DocFx which is developed and maintained by the .NET team. DocFx is the underlying technology behind the newly redesigned docs.microsoft.com which represents a clean, modern way we are presenting documentation on sites going forward. We have already migrated documentation for several products including Azure and .NET Core onto the new platform and more are actively in transition.
DocFx is similar to other platforms like Jekyll or ReadTheDocs where you write the content in Markdown, provide some high level template structure to your site, run the tool of choice and out comes a site with fully rendered html, CSS, and required JavaScript. In addition to supporting Markdown files, DocFx can also process Swagger json files, as well as managed code objects.
Introducing DocFx Build Task
DocFx gives us a lot of power to create great documentation for our product, but I wanted a way to be able to put that into a continuous integration / continuous delivery pipeline. My original approach to this problem was to create a build pipeline in VSTS that would download and install something like Chocolately, use Chocolately to grab the latest DocFx package, then run a command line build task that would invoke DocFx against our project. Unfortunately, that solution did not pan out as I had hoped and ended up being a bit messy overall.
So, I wrote a VSTS build task extension! My extension is called DocFx Build Tasks and it aims provide an easy way to integrate DocFx into your build pipeline so you can generate content that can later be pushed out through a release pipeline. The agent is in a first release, so try it out, give me feedback and let me know if you feel anything that is missing.
Example Walkthrough
We can now try this extension out and see what kind of workflow we might be able to get working. For my example project, I started with the DocFx seed project. I created a new Git repository in VSTS and pushed this code base into there. No other changes were made to the seed project.
Install the Extension
Open the extension from the VSTS Marketplace. For VSTS click “Install” for TFS click “Download”
Follow the instructions to complete the installation of the extension (in my case, I am using VSTS and that is how I will refer to it from now on).
Configure Build
Navigate to the “Build” hub within VSTS. Click “+ New” to create a new build.
You can select whichever template you would like as we are going to ultimately reconfigure it anyways.
Assuming you pick “Visual Studio”, you end up with the following setup.
Remove every existing task within the setup. Click “+ Add Task” and add the following two tasks:
· Create DocFx Documentation
· Copy and Publish Build Artifacts
Your pipeline should look like the following:
For the Create DocFx Documentation step, in most cases, you only need to provide a path to the docfx.json file in your source control.
If you need to override how DocFx is invoked, you can specify those options as well. We are going to want to publish our generated content to a web site ultimately so we will need to configure the copy and publish build artifacts.
Save and queue the build and your site should be generated within a few minutes and published as an artifact from our build.
Deploy to a Web App
In my example, I am using an Azure Web App to deploy my site’s content to. I went to the Azure portal, created a new web app and then reset the credentials to support ftp deployment.
Back in VSTS, I navigate to the “Release” hub and click the “+” to create a new release.
I started with an Empty release definition for this example.
Click “Next,” select the name of the build definition you created in the previous step, you can choose if you want it to implement continuous deployment or not, and I left mine as the “Hosted” build queue. Click “Create.”
In your new release definition, setup your environments. This can follow whatever flow makes sense for your requirements but an example flow could be something like Draft -> QA -> Live. Select an environment and add a single task:
· FTP Upload
For Authentication Method, I used FTP Service Endpoint. This allows me to create a generic service endpoint based on the reset FTP credentials of the site I setup. Once I create that service endpoint, I can reference that within the task. Select the source folder to the artifacts folder you previously built. The remote directory for an Azure web app would be /site/wwwroot.
A couple notes, in the Advanced section, you want to make sure you enable “Overwrite” as well as “Preserve file paths.” Without the second option, everything would be copied to a flat file format which would cause the site to not render correctly. The full release task is shown below:
Save and start a new release and in about a minute, you should have your newly generated CI/CD DevOps friendly documentation site.
We have seen in this example how we can now incorporate documentation writing as part of a DevOps mindset. Connecting written content to a continuous delivery pipeline provides an opportunity for end customers to ensure they are up to date on the latest and greatest details about your product. As far as the extension shown here is concerned, this is its first release and I would love to hear how it works for you or if there are any suggestions for improvement.
Premier Support for Developers provides strategic technology guidance, critical support coverage, and a range of essential services to help teams optimize development lifecycles and improve software quality. Contact your Application Development Manager (ADM) or email us to learn more about what we can do for you.
Hi, i’m getting this error “##[error]Unable to locate executable file: ‘/home/vsts/work/_tasks/DocFxTask_e0923c33-09f9-43a0-a8af-86b7d0d76b03/0.1.19/tools/nuget.exe’. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable. Also check the file mode to verify the file is executable.” when running Create DocFx Documentation. Can you help?