Document generator from cfn template files.
Project description
cfn-docgen - AWS CloudFormation Document Generator
Generate human-readable documents from AWS CloudFormation yaml/json templates.
Notice
We have made breaking changes from v0.7 to current versions.
Example
Given that you created some cfn template yaml file. When you use cfn-docgen cli. Then, you can generate markdown document.
$ cfn-docgen docgen \
--format markdown \
--source docs/sample-template.yaml \
--dest ./docs/
[INFO] successfully generate document [./docs/sample-template.md] from template [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, see docs folder
Install and How to use
CLI
$ pip install cfn-docgen
# you can also geenrate a document from a template at S3 bucket and upload it directory.
$ cfn-docgen docgen \
--source s3://bucket/prefix/sample-template.yaml \
--dest s3://bucket/prefix/sample-template.md
[INFO] successfully generate document [s3://bucket/prefix/sample-template.md] from template [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.yaml
1 directory, 2 files
$ cfn-docgen docgen \
--source ./templates/ \
--dest s3://bucket/documents/
[INFO] successfully generate document [s3://bucket/documents/sample-template-1.md] from template [./templates/sample-template-1.yaml]
[INFO] successfully generate document [s3://bucket/documents/subfolder/sample-template-2.md] from template [./templates/subfolder/sample-template-2.yaml]
Docker Image
# pull image from DockerHub
$ docker pull horietakehiro/cfn-docgen:latest
# local directory(before)
$ tree /tmp/sample/
/tmp/sample/
└── sample-template.json
0 directories, 1 files
# run as command
$ docker run \
-v /tmp/sample/:/tmp/ \
horietakehiro/cfn-docgen:latest docgen \
--source /tmp/sample-template.json \
--dest /tmp/
[INFO] successfully generate document [/tmp/sample-template.md] from template [/tmp/sample-template.json]
# local directory(after)
$ tree /tmp/sample/
/tmp/sample/
├── sample-template.json
└── sample-template.md
0 directories, 2 files
API
from cfn_docgen import (
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",
)
)
Serverless
You can also use cfn-docgen on AWS Cloud as serverless application.
You can deploy resources at AWS Serverless Application Repository.
Once deployed, tha S3 bucket named cfn-docgen-${AWS::AccountId}-${AWS::Region}
is created on your account.
When you upload cfn template json/yaml files at templates/
folder of the bucket, cfn-docgen-serverless automatically will be triggered and generates markdown docments for them at documents/
folder.
Embedding Descirptions
Top level descriptions
You can embed description for the template at top level Metadata
section 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 environment
Conditions:
EnvCondition: Check if the value of parameter `EnvType` is `prod`
Rules:
RegionRule: This template is available only in ap-northeast-1
Then, the generated description will be like below.
Resources and Properties description
You can embed descriptions for resources and their properties in Metadata
section in each resources.
Resources:
VPC:
Metadata:
CfnDocgen:
Description: アプリケーションサーバを稼働させるために使用するVPC
Properties:
EnableDnsHostnames: アプリケーションサーバのホスト名でパブリックIPを名前解決できるように有効化する
Type: AWS::EC2::VPC
Properties:
CidrBlock: ...
Then, the generated description will be like below.
Integration with AWS CDK
cfn-docgen can generate documents from AWS-CDK-generated templates, and you can also embed descriptions in cdk codes like below.
from aws_cdk import (
Stack,
aws_ec2 as ec2,
)
from constructs import Construct
from typing import Any
from cfn_docgen.domain.model.cfn_template import (
CfnTemplateMetadataCfnDocgenDefinition as Metadata,
CfnTemplateResourceMetadataDefinition as ResourceMetadata,
CfnTemplateResourceMetadataCfnDocgenDefinition as CfnDocgen
)
class CfnDocgenSampleCdkStack(Stack):
def __init__(self, scope: Construct, construct_id: str, **kwargs:Any) -> None:
super().__init__(scope, construct_id, **kwargs)
# top-level description for the stack
self.add_metadata(
"CfnDocgen", Metadata(
Description="top-level-description"
).model_dump(),
)
self.vpc_construct = ec2.Vpc(self, "VpcConstruct", max_azs=1)
# resource-level descriptions
self.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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cfn_docgen-0.11.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4334c015800eca01718e1e6d3bfb879fffc1009b7087a26b653f35e8350ce0e2 |
|
MD5 | addbeafb8f31dfaf06bea6c199338547 |
|
BLAKE2b-256 | ccbfac48d2f2fa1443d50e16822cba22dd308e7c9eca447a7e885fce1b80fd05 |