Package: cfn-docgen
cfn-docgen - AWS CloudFormation Document GeneratorGenerate human-readable documents from AWS CloudFormation yaml/json templates.NoticeWe have made breaking changes fromv0.7to current versions.ExampleGiven that you created some cfn template yaml file. When you use cfn-docgen cli. Then, you can generate markdown document.$cfn-docgendocgen\--formatmarkdown\--sourcedocs/sample-template.yaml\--dest./docs/[INFO]successfullygeneratedocument[./docs/sample-template.md]fromtemplate[docs/sample-template.yaml]The left image is a source cfn template file and the right image is a generated document markdown.For full example, seedocs folderInstall and How to useCLI$pipinstallcfn-docgen# you can also geenrate a document from a template at S3 bucket and upload it directory.$cfn-docgendocgen\--sources3://bucket/prefix/sample-template.yaml\--dests3://bucket/prefix/sample-template.md[INFO]successfullygeneratedocument[s3://bucket/prefix/sample-template.md]fromtemplate[s3://bucket/prefix/sample-template.yaml]# and you can generate multiple documents from templates in direcotry(or s3 bucket prefix) at once$tree./templates/
./templates/
├──sample-template-1.yaml
└──subfolder└──sample-template-2.yaml1directory,2files
$cfn-docgendocgen\--source./templates/\--dests3://bucket/documents/[INFO]successfullygeneratedocument[s3://bucket/documents/sample-template-1.md]fromtemplate[./templates/sample-template-1.yaml][INFO]successfullygeneratedocument[s3://bucket/documents/subfolder/sample-template-2.md]fromtemplate[./templates/subfolder/sample-template-2.yaml]Visual Studio Code ExtensionYou can use cfn-docgen asVisual Studio Code ExtensionDocker Image# pull image from DockerHub$dockerpullhorietakehiro/cfn-docgen:latest# local directory(before)$tree/tmp/sample/
/tmp/sample/
└──sample-template.json0directories,1files# run as command$dockerrun\-v/tmp/sample/:/tmp/\horietakehiro/cfn-docgen:latestdocgen\--source/tmp/sample-template.json\--dest/tmp/[INFO]successfullygeneratedocument[/tmp/sample-template.md]fromtemplate[/tmp/sample-template.json]# local directory(after)$tree/tmp/sample/
/tmp/sample/
├──sample-template.json
└──sample-template.md0directories,2filesAPIfromcfn_docgenimport(CfnDocgenService,CfnDocgenServiceCommandInput,CfnTemplateSource,CfnDocumentDestination)service=CfnDocgenService.with_default()service.main(command_input=CfnDocgenServiceCommandInput(template_source=CfnTemplateSource("s3://bucket/template.yaml",service.context),document_dest=CfnDocumentDestination("s3://bucket/document.md",service.context),fmt="markdown",))ServerlessYou can also use cfn-docgen on AWS Cloud as serverless application.You can deploy resources atAWS Serverless Application Repository.Once deployed, tha S3 bucket namedcfn-docgen-${AWS::AccountId}-${AWS::Region}is created on your account.When you upload cfn template json/yaml files attemplates/folder of the bucket, cfn-docgen-serverless automatically will be triggered and generates markdown docments for them atdocuments/folder.FeaturesEmbedding DescirptionsTop level descriptionsYou can embed description for the template at top levelMetadatasection like this, then markdown document will be generated from it.Metadata:CfnDocgen:Description:|このテンプレートファイル東京リージョン上で以下のリソースを作成します- VPC- パブリックサブネット(2AZに1つずつ)![Archtecture](./images/sample-template.drawio.png)**注意点**- このテンプレートファイルは**東京リージョン**上でのみの使用に制限しています- このテンプレートファイルを使用する前に、[東京リージョン上に作成可能なVPCの最大数の設定](https://ap-northeast-1.console.aws.amazon.com/servicequotas/home/services/vpc/quotas/L-F678F1CE)を確認することを推奨します(デフォルトは5VPC)**Then, the generated description will be like below.You can also embed descriptions for each sections - Mappings, Conditions, Rules.Metadata:CfnDocgen:Mappings:CidrBlockMap:CidrBlocks for each environmentConditions:EnvCondition:Check if the value of parameter `EnvType` is `prod`Rules:RegionRule:This template is available only in ap-northeast-1Then, the generated description will be like below.Resources and Properties descriptionYou can embed descriptions for resources and their properties inMetadatasection in each resources.Resources:VPC:Metadata:CfnDocgen:Description:アプリケーションサーバを稼働させるために使用するVPCProperties:EnableDnsHostnames:アプリケーションサーバのホスト名でパブリックIPを名前解決できるように有効化するType:AWS::EC2::VPCProperties:CidrBlock:...Then, the generated description will be like below.Integration with AWS CDKcfn-docgen can generate documents from AWS-CDK-generated templates, and you can also embed descriptions in cdk codes like below.fromaws_cdkimport(Stack,aws_ec2asec2,)fromconstructsimportConstructfromtypingimportAnyfromcfn_docgen.domain.model.cfn_templateimport(CfnTemplateMetadataCfnDocgenDefinitionasMetadata,CfnTemplateResourceMetadataDefinitionasResourceMetadata,CfnTemplateResourceMetadataCfnDocgenDefinitionasCfnDocgen)classCfnDocgenSampleCdkStack(Stack):def__init__(self,scope:Construct,construct_id:str,**kwargs:Any)->None:super().__init__(scope,construct_id,**kwargs)# top-level description for the stackself.add_metadata("CfnDocgen",Metadata(Description="top-level-description").model_dump(),)self.vpc_construct=ec2.Vpc(self,"VpcConstruct",max_azs=1)# resource-level descriptionsself.vpc_construct.node.default_child.cfn_options.metadata=ResourceMetadata(CfnDocgen=CfnDocgen(Description="resource-level-description")).model_dump()Then, the table of contents of generated document will be like below.Integration with custom resource specificationYou can define custom resource specificationlike thisand generate documents for them.$cfn-docgendocgen\-sdocs/sample-template.yaml\-sdocs/sample-template.md\-cdocs/custom-specification.jsonGenerate skeletonsYou can generate definition skeletons for each resource types.$cfn-docgenskeleton--typeAWS::EC2::VPC--formatyaml
Type:AWS::EC2::VPC
Metadata:CfnDocgen:Description:''Properties:{}Properties:InstanceTenancy:StringIpv4NetmaskLength:IntegerCidrBlock:StringIpv4IpamPoolId:StringEnableDnsSupport:BooleanEnableDnsHostnames:BooleanTags:-Key:StringValue:String

$cfn-docgenskeleton--typeAWS::EC2::VPC--formatjson{"Type":"AWS::EC2::VPC","Metadata":{"CfnDocgen":{"Description":"","Properties":{}}},"Properties":{"InstanceTenancy":"String","Ipv4NetmaskLength":"Integer","CidrBlock":"String","Ipv4IpamPoolId":"String","EnableDnsSupport":"Boolean","EnableDnsHostnames":"Boolean","Tags":[{"Key":"String","Value":"String"}]}}