Document generator from cfn template files.
Project description
cfn-docgen
Generate human-readable documents from AWS CloudFormation yaml/json templates.
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
You can embed custom descriptions in Metadata
at top level and each resources like below.
Install
CLI
$ pip install cfn-docgen
# you can also geenrate a document from a template at S3 bucket and upload it directory.
$ cfn-docgen \
--source s3://bucket/templates/sample-template.yaml \
--dest s3://bucket/documents/ \
--format markdown
# and you can generate multiple documents from templates in direcotry(or s3 bucket prefix)
$ cfn-docgen \
--source ./templates/ \
--dest ./documents/ \
--format markdown
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/ \
--fmt markdown
# 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)**
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
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 for application to be deployed
Properties:
EnableDnsHostnames: application instances in public subnet have to be resolved their names from public internet.
Type: AWS::EC2::VPC
Properties:
CidrBlock: ...
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.10.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b55ea3ea89470b6a0f2430664158b1a081d9b22c03952974dd13514b45db3c6 |
|
MD5 | 82fcf63c0e390d7b80a23d092eb3c63c |
|
BLAKE2b-256 | 180e96ff771a3c45579a00878d269685ae629428834e6aa6d1c6b4dcdb5310f7 |