Microsoft Workloads on AWS
How to build an automated C# code documentation generator using AWS DevOps
In this blog post, we will show you how to create a documentation solution on the Amazon Web Services (AWS) Cloud that automatically generates and publishes a technical documentation website for a .NET project, based on source code comments, API definitions, and Markdown documents included in the project.
Having a technical documentation website improves developer productivity, and generating the documentation automatically ensures that the site is always up-to-date. Without this automation, developers need to continually update the documentation, creating operational overhead and increasing the risk of documentation errors.
This solution also implements additional best practices for technical documentation, such as cost-effective hosting, a consistent structure, and version history. The documentation is stored in a centralized location with access control and gets updated with every code check-in. It contains consistent structure, including a table of contents, class descriptions and links to inheritance (if any), method descriptions along with signature and return type, and much more. This post describes various AWS services that are used to build the solution, including AWS CodeBuild, Amazon Simple Storage Service (Amazon S3), AWS Lambda, and Amazon CloudFront.
Solution overview
This post uses DocFx and AWS to automatically generate code documentation for a C# project. DocFx is an open-source documentation generator for .NET projects that builds a static HTML website from XML code comments, REST API definition (Swagger) files, and Markdown documents in the project. The solution automatically generates updated documentation during every build, triggered by an event on the AWS CodeCommit repository. The documentation website is then hosted on Amazon S3 and distributed through Amazon CloudFront, as shown in Figure 1 below:
Figure1: Architecture diagram for proposed solution
A developer committing code to the AWS CodeCommit repository initiates a build in AWS CodeBuild. During the build, AWS CodeBuild sets up DocFx in the build environment. After the build completes, AWS CodeBuild runs a Lambda function that checks if the project version already has documentation in Amazon S3.
If the documentation doesn’t exist, AWS CodeBuild runs DocFx to generate the documentation website and uploads the HTML pages to Amazon S3. AWS CodeBuild then runs another Lambda function that updates the Amazon S3 website to include a link to the new documentation. Finally, the Amazon CloudFront distribution synchronizes with the Amazon S3 bucket to serve as the public endpoint for the documentation.
Walkthrough
To deploy the solution, follow these high-level steps:
- Use an AWS CloudFormation template to deploy the AWS infrastructure.
- Configure the AWS Codebuild Target.
- Configure the C# project to support DocFx.
Deploy AWS infrastructure
After launching the AWS CloudFormation stack, it will implement this solution in your AWS account, creating all the necessary AWS resources (including AWS Identity and Access Management (IAM) roles, Amazon S3 buckets, an AWS CodePipeline pipeline, an Amazon CloudFront distribution, and so on).
Follow these steps to deploy the solution using AWS CloudFormation:
- Step 1: Copy the below AWS CloudFormation template:
-
- AWS CodeBuild with a Windows image:
-
- AWS CodeBuild with a Linux image:
- Step 2: Sign in to your AWS account and navigate to the CloudFormation console.
- Step 3: Choose Create stack
- Step 4: On the Create stack page, for Prepare template, choose Template is ready.
- Step 5: For Template source, choose the option Upload the template file. Click Choose file option and upload the AWS CloudFormation template file created by copying content from step 1.
- Step 6: Choose Next. (Alternatively, you can navigate to this link and the stack will use an AWS CloudFormation template stored in Amazon S3.)
Figure 2: Create stack on AWS CloudFormation.
- Step 7: For Stack name, enter a name for the stack (such as DocumentGeneratorStack). For ArtifactStoreBucketName, enter a name for the Amazon S3 bucket where the AWS CodePipeline artifacts will be stored. For CodeBuildProjectName, enter a name for the AWS CodeBuild project that the solution will create. For CodeCommitRepositoryName, enter a name for the AWS CodeCommit repository that the solution will create to hold your C# project. For DocumentationBucketName, enter a name for the Amazon S3 bucket where the generated code documentation will be stored. For LoggingBucketName, enter a name for the Amazon S3 bucket where the solution logs will be stored.
Figure 3: Specify stack details on AWS CloudFormation.
- Step 8: Select I acknowledge that AWS CloudFormation might create IAM resources with custom names, then select Submit.
Figure4: Acknowledgment checkbox for IAM resources creation.
Configuring the AWS CodeBuild target
To configure AWS CodeBuild, add a buildspec file to the C# project.
You can use one of these example buildspec files:
For a C# project building on Windows, use below buildspec.yml:
For a C# project building on Linux, use below buildspec.yml:
Configuring the C# project
Update the C# project with the following steps to enable automated documentation generation with DocFx:
- Add the DocFx configuration file.
- Add Markdown index files that will be the section home pages for the documentation website.
- Add table of contents (TOC) files so DocFx will understand the project’s folder structure.
For the DocFX configuration file, use below DocFx.json. (See using DocFx for documentation of each setting.)
Add this file to the base folder of the C# project, with the name DocFx.json.
Now, create an api folder in the C# project if it doesn’t exist. You will need to create index and TOC files for the base folder of the project and the api folder.
In the base folder of the project, create a file named index.md. Populate the file with below content:
Next, create a file named toc.yml. Populate the file with below content:
In the api folder, create a file named index.md. Populate the file with below content:
## Can add documentation related details here in markdown format
Next, create a file named toc.yml (in the api folder). Populate the file with below content:
Now, push your C# project to the AWS CodeCommit repository using the main branch (see the AWS CodeCommit user guide for details).
Note: AWS restricts AWS CodeCommit repositories to authorized users. You will need to add a policy allowing read/write access to the created repository for your policy IAM user.
The solution configures the AWS CodePipeline project to monitor an AWS CodeCommit branch named main.
Every code push event in the AWSCodeCommit repository triggers the AWS CodePipeline to build and update the static website. The link to open the documentation website can be found on the Amazon CloudFront page in the AWS Management Console.
Cleaning up
To avoid incurring future charges on your AWS account, you will need to delete the resources created by this solution. You can delete all resources by deleting the Amazon CloudFormation stack. For any resources that are changed after deploying the stack (for example, Amazon S3 buckets), you will need to empty them before deleting the stack.
Conclusion
In this blog post, we have discussed how to create an automated C# code documentation generation system. You can use this system to generate and host real-time, encrypted documentation, with access restricted to a relevant audience.
AWS can help you assess how your company can get the most out of cloud. Join the millions of AWS customers that trust us to migrate and modernize their most important applications in the cloud. To learn more on modernizing Windows Server or SQL Server, visit Windows on AWS. Contact us to start your migration journey today.