Skip to content

Commit 2029e9a

Browse files
dliggatdliggat
authored
Fixes to automated document generation (#417)
* Minor fixes for document generation * Minor fixes to variables * Fix doc * Adding workflow_run key
1 parent 07637f7 commit 2029e9a

File tree

4 files changed

+107
-91
lines changed

4 files changed

+107
-91
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 46 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
on: workflow_dispatch
1+
on:
2+
workflow_dispatch:
3+
workflow_run:
4+
workflows: ["Merge Release Branch"]
5+
branches: [master]
6+
types:
7+
- completed
28

39
name: Generate Documentation
410

@@ -17,15 +23,23 @@ jobs:
1723
sudo apt install librsvg2-bin
1824
sudo apt install 'fonts-dejavu*'
1925
20-
- name: Mkdir documentation
26+
- name: Setup Env
27+
id: setup
28+
env:
29+
PREFIX: AWS-SEA
30+
SUFFIX: Documentation
2131
run: |
22-
mkdir documentation
32+
mkdir ${PREFIX}-${SUFFIX}
33+
echo ::set-output name=prefix::$(echo "${PREFIX}")
34+
echo ::set-output name=suffix::$(echo "${SUFFIX}")
35+
echo ::set-output name=dir::$(echo "${PREFIX}-${SUFFIX}")
36+
2337
2438
- name: PDF output 0
2539
uses: docker://pandoc/latex:2.10
2640
with:
2741
args: >
28-
--output=documentation/0-AWS-SEA-Solution-Summary.pdf
42+
--output=${{ steps.setup.outputs.dir }}/0-${{ steps.setup.outputs.prefix }}-Solution-Summary.pdf
2943
--from=gfm
3044
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
3145
-V linkcolor:blue
@@ -40,7 +54,7 @@ jobs:
4054
uses: docker://pandoc/latex:2.10
4155
with:
4256
args: >
43-
--output=documentation/1-AWS-SEA-Installation-Guide.pdf
57+
--output=${{ steps.setup.outputs.dir }}/1-${{ steps.setup.outputs.prefix }}-Installation-Guide.pdf
4458
--from=gfm
4559
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
4660
-V linkcolor:blue
@@ -55,7 +69,7 @@ jobs:
5569
uses: docker://pandoc/latex:2.10
5670
with:
5771
args: >
58-
--output=documentation/2a-AWS-SEA-Config-File-Options-ToC.pdf
72+
--output=${{ steps.setup.outputs.dir }}/2a-${{ steps.setup.outputs.prefix }}-Config-File-Options-ToC.pdf
5973
--from=gfm
6074
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
6175
-V linkcolor:blue
@@ -68,13 +82,13 @@ jobs:
6882
6983
- name: Copy file output 2b
7084
run: |
71-
cp reference-artifacts/config.example.json documentation/2b-AWS-SEA-config.example.json
85+
cp reference-artifacts/config.example.json ${{ steps.setup.outputs.dir }}/2b-${{ steps.setup.outputs.prefix }}-config.example.json
7286
7387
- name: PDF output 2c
7488
uses: docker://pandoc/latex:2.10
7589
with:
7690
args: >
77-
--output=documentation/2c-AWS-SEA-Multi-file-Config-Capabilities.pdf
91+
--output=${{ steps.setup.outputs.dir }}/2c-${{ steps.setup.outputs.prefix }}-Multi-file-Config-Capabilities.pdf
7892
--from=gfm
7993
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
8094
-V linkcolor:blue
@@ -89,7 +103,7 @@ jobs:
89103
uses: docker://pandoc/latex:2.10
90104
with:
91105
args: >
92-
--output=documentation/2d-AWS-SEA-Config-Sample-Snippets.pdf
106+
--output=${{ steps.setup.outputs.dir }}/2d-${{ steps.setup.outputs.prefix }}-Config-Sample-Snippets.pdf
93107
--from=gfm
94108
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
95109
-V linkcolor:blue
@@ -102,13 +116,13 @@ jobs:
102116
103117
- name: Copy file output 2e
104118
run: |
105-
cp reference-artifacts/Third-Party/firewall-example.txt documentation/2e-AWS-SEA-firewall-example.txt
119+
cp reference-artifacts/Third-Party/firewall-example.txt ${{ steps.setup.outputs.dir }}/2e-${{ steps.setup.outputs.prefix }}-firewall-example.txt
106120
107121
- name: PDF output 2f
108122
uses: docker://pandoc/latex:2.10
109123
with:
110124
args: >
111-
--output=documentation/2f-AWS-SEA-Firewall-config-Customizations.pdf
125+
--output=${{ steps.setup.outputs.dir }}/2f-${{ steps.setup.outputs.prefix }}-Firewall-config-Customizations.pdf
112126
--from=gfm
113127
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
114128
-V linkcolor:blue
@@ -119,11 +133,26 @@ jobs:
119133
--pdf-engine=xelatex
120134
./reference-artifacts/master-config-sample-snippets/firewall_file_available_variables.md
121135
136+
- name: PDF output 2g
137+
uses: docker://pandoc/latex:2.10
138+
with:
139+
args: >
140+
--output=${{ steps.setup.outputs.dir }}/2g-${{ steps.setup.outputs.prefix }}-logging-locations.pdf
141+
--from=gfm
142+
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
143+
-V linkcolor:blue
144+
-V geometry:paperwidth=8.5in
145+
-V geometry:paperheight=11in
146+
-V geometry:margin=.8in
147+
-V documentclass=report
148+
--pdf-engine=xelatex
149+
docs/architectures/pbmm/log-file-locations.md
150+
122151
- name: PDF output 3
123152
uses: docker://pandoc/latex:2.10
124153
with:
125154
args: >
126-
--output=documentation/3-AWS-SEA-Operations-Troubleshooting-Guide.pdf
155+
--output=${{ steps.setup.outputs.dir }}/3-${{ steps.setup.outputs.prefix }}-Operations-Troubleshooting-Guide.pdf
127156
--from=gfm
128157
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
129158
-V linkcolor:blue
@@ -140,7 +169,7 @@ jobs:
140169
uses: docker://pandoc/latex:2.10
141170
with:
142171
args: >
143-
--output=documentation/4-AWS-SEA-Developer-Guide.pdf
172+
--output=${{ steps.setup.outputs.dir }}/4-${{ steps.setup.outputs.prefix }}-Developer-Guide.pdf
144173
--from=gfm
145174
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
146175
-V linkcolor:blue
@@ -155,7 +184,7 @@ jobs:
155184
uses: docker://pandoc/latex:2.10
156185
with:
157186
args: >
158-
--output=documentation/5-AWS-SEA-PBMM-Architecture.pdf
187+
--output=${{ steps.setup.outputs.dir }}/5-${{ steps.setup.outputs.prefix }}-PBMM-Architecture.pdf
159188
--from=gfm
160189
--resource-path=.:docs/architectures/pbmm:docs/installation:docs/operations
161190
-V linkcolor:blue
@@ -168,8 +197,8 @@ jobs:
168197
169198
- name: Zip
170199
run: |
171-
zip -r documentation.zip documentation/
200+
zip -r ${{ steps.setup.outputs.dir }}.zip ${{ steps.setup.outputs.dir }}/
172201
- uses: actions/upload-artifact@master
173202
with:
174-
name: documentation.zip
175-
path: documentation.zip
203+
name: ${{ steps.setup.outputs.dir }}
204+
path: ${{ steps.setup.outputs.dir }}.zip

‎docs/architectures/pbmm/architecture.md‎

Lines changed: 57 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -10,80 +10,63 @@ It is anticipated we will offer multiple sample architectures with the AWS SEA s
1010

1111
<!-- TOC depthFrom:2 -->
1212

13-
- [AWS Secure Environment Architecture](#aws-secure-environment-architecture)
14-
- [Table of Contents](#table-of-contents)
15-
- [1. Introduction](#1-introduction)
16-
- [1.1. Purpose of Document](#11-purpose-of-document)
17-
- [1.2. Overview](#12-overview)
18-
- [1.3. Document Convention](#13-document-convention)
19-
- [1.3.1. AWS Account Numbers](#131-aws-account-numbers)
20-
- [1.3.2. JSON Annotation](#132-json-annotation)
21-
- [1.3.3. IP Addresses](#133-ip-addresses)
22-
- [1.4. Department Naming](#14-department-naming)
23-
- [1.5. Relationship to AWS Landing Zone](#15-relationship-to-aws-landing-zone)
24-
- [2. Account Structure](#2-account-structure)
25-
- [2.1. Accounts](#21-accounts)
26-
- [2.2. Master Account](#22-master-account)
27-
- [2.2.1. AWS SSO](#221-aws-sso)
28-
- [2.2.2. Organizational Units](#222-organizational-units)
29-
- [2.2.2.1. Core OU](#2221-core-ou)
30-
- [2.2.2.2. Central OU](#2222-central-ou)
31-
- [2.2.2.3. Functional OU: Sandbox](#2223-functional-ou-sandbox)
32-
- [2.2.2.4. Functional OU: UnClass](#2224-functional-ou-unclass)
33-
- [2.2.2.5. Functional OU: Dev](#2225-functional-ou-dev)
34-
- [2.2.2.6. Functional OU: Test](#2226-functional-ou-test)
35-
- [2.2.2.7. Functional OU: Prod](#2227-functional-ou-prod)
36-
- [2.2.2.8. Suspended OU](#2228-suspended-ou)
37-
- [2.3. Mandatory Accounts](#23-mandatory-accounts)
38-
- [2.3.1. Master](#231-master)
39-
- [2.3.2. Perimeter](#232-perimeter)
40-
- [2.3.3. Shared Network](#233-shared-network)
41-
- [2.3.4. Operations](#234-operations)
42-
- [2.3.5. Log Archive](#235-log-archive)
43-
- [2.3.6. Security](#236-security)
44-
- [2.4. Functional Accounts](#24-functional-accounts)
45-
- [2.5. Account Level Settings](#25-account-level-settings)
46-
- [2.6. Private Marketplace](#26-private-marketplace)
47-
- [3. Networking](#3-networking)
48-
- [3.1. Overview](#31-overview)
49-
- [3.2. Perimeter](#32-perimeter)
50-
- [3.2.1. IP Ranges](#321-ip-ranges)
51-
- [3.3. Shared Network](#33-shared-network)
52-
- [3.3.1. Transit Gateway](#331-transit-gateway)
53-
- [3.3.2. Endpoint VPC](#332-endpoint-vpc)
54-
- [3.3.3. Endpoint VPC: Interface Endpoints](#333-endpoint-vpc-interface-endpoints)
55-
- [3.3.4. Endpoint VPC: Hybrid DNS](#334-endpoint-vpc-hybrid-dns)
56-
- [3.3.4.1. Within The Cloud](#3341-within-the-cloud)
57-
- [3.3.4.2. From Cloud to On-Premises](#3342-from-cloud-to-on-premises)
58-
- [3.3.4.3. From On-Premises to Cloud](#3343-from-on-premises-to-cloud)
59-
- [3.3.5. Workload VPCs](#335-workload-vpcs)
60-
- [3.3.5.1. Security Groups](#3351-security-groups)
61-
- [3.3.5.2. NACLs](#3352-nacls)
62-
- [3.3.6. Central VPC](#336-central-vpc)
63-
- [3.3.6.1. Domain Joining](#3361-domain-joining)
64-
- [3.3.7. Sandbox VPC](#337-sandbox-vpc)
65-
- [4. Authorization and Authentication](#4-authorization-and-authentication)
66-
- [4.1. Relationship to the Master Account](#41-relationship-to-the-master-account)
67-
- [4.2. Break Glass Accounts](#42-break-glass-accounts)
68-
- [4.3. Control Plane Access via AWS SSO](#43-control-plane-access-via-aws-sso)
69-
- [4.3.1. SSO User Roles](#431-sso-user-roles)
70-
- [4.3.2. Principal Authorization](#432-principal-authorization)
71-
- [4.4. Root Authorization](#44-root-authorization)
72-
- [4.5. Service Roles](#45-service-roles)
73-
- [4.6. Service Control Policies](#46-service-control-policies)
74-
- [4.6.1. PBMM Only](#461-pbmm-only)
75-
- [4.6.2. PBMM Unclass Only](#462-pbmm-unclass-only)
76-
- [4.6.3. PBMM Guardrails (Parts 1 and 2)](#463-pbmm-guardrails-parts-1-and-2)
77-
- [4.6.3.1. Encryption at Rest](#4631-encryption-at-rest)
78-
- [4.6.4. Quarantine Deny All](#464-quarantine-deny-all)
79-
- [4.6.5. Quarantine New Object](#465-quarantine-new-object)
80-
- [5. Logging and Monitoring](#5-logging-and-monitoring)
81-
- [5.1. CloudTrail](#51-cloudtrail)
82-
- [5.2. VPC Flow Logs](#52-vpc-flow-logs)
83-
- [5.3. GuardDuty](#53-guardduty)
84-
- [5.4. Config](#54-config)
85-
- [5.5. Cloudwatch Logs](#55-cloudwatch-logs)
86-
- [5.6. SecurityHub](#56-securityhub)
13+
- [1. Introduction](#1-introduction)
14+
- [1.1. Purpose of Document](#11-purpose-of-document)
15+
- [1.2. Overview](#12-overview)
16+
- [1.3. Document Convention](#13-document-convention)
17+
- [1.3.1. AWS Account Numbers](#131-aws-account-numbers)
18+
- [1.3.2. JSON Annotation](#132-json-annotation)
19+
- [1.3.3. IP Addresses](#133-ip-addresses)
20+
- [1.4. Department Naming](#14-department-naming)
21+
- [1.5. Relationship to AWS Landing Zone](#15-relationship-to-aws-landing-zone)
22+
- [2. Account Structure](#2-account-structure)
23+
- [2.1. Accounts](#21-accounts)
24+
- [2.2. Master Account](#22-master-account)
25+
- [2.2.1. AWS SSO](#221-aws-sso)
26+
- [2.2.2. Organizational Units](#222-organizational-units)
27+
- [2.3. Mandatory Accounts](#23-mandatory-accounts)
28+
- [2.3.1. Master](#231-master)
29+
- [2.3.2. Perimeter](#232-perimeter)
30+
- [2.3.3. Shared Network](#233-shared-network)
31+
- [2.3.4. Operations](#234-operations)
32+
- [2.3.5. Log Archive](#235-log-archive)
33+
- [2.3.6. Security](#236-security)
34+
- [2.4. Functional Accounts](#24-functional-accounts)
35+
- [2.5. Account Level Settings](#25-account-level-settings)
36+
- [2.6. Private Marketplace](#26-private-marketplace)
37+
- [3. Networking](#3-networking)
38+
- [3.1. Overview](#31-overview)
39+
- [3.2. Perimeter](#32-perimeter)
40+
- [3.2.1. IP Ranges](#321-ip-ranges)
41+
- [3.3. Shared Network](#33-shared-network)
42+
- [3.3.1. Transit Gateway](#331-transit-gateway)
43+
- [3.3.2. Endpoint VPC](#332-endpoint-vpc)
44+
- [3.3.3. Endpoint VPC: Interface Endpoints](#333-endpoint-vpc-interface-endpoints)
45+
- [3.3.4. Endpoint VPC: Hybrid DNS](#334-endpoint-vpc-hybrid-dns)
46+
- [3.3.5. Workload VPCs](#335-workload-vpcs)
47+
- [3.3.6. Central VPC](#336-central-vpc)
48+
- [3.3.7. Sandbox VPC](#337-sandbox-vpc)
49+
- [4. Authorization and Authentication](#4-authorization-and-authentication)
50+
- [4.1. Relationship to the Master Account](#41-relationship-to-the-master-account)
51+
- [4.2. Break Glass Accounts](#42-break-glass-accounts)
52+
- [4.3. Control Plane Access via AWS SSO](#43-control-plane-access-via-aws-sso)
53+
- [4.3.1. SSO User Roles](#431-sso-user-roles)
54+
- [4.3.2. Principal Authorization](#432-principal-authorization)
55+
- [4.4. Root Authorization](#44-root-authorization)
56+
- [4.5. Service Roles](#45-service-roles)
57+
- [4.6. Service Control Policies](#46-service-control-policies)
58+
- [4.6.1. PBMM Only](#461-pbmm-only)
59+
- [4.6.2. PBMM Unclass Only](#462-pbmm-unclass-only)
60+
- [4.6.3. PBMM Guardrails (Parts 1 and 2)](#463-pbmm-guardrails-parts-1-and-2)
61+
- [4.6.4. Quarantine Deny All](#464-quarantine-deny-all)
62+
- [4.6.5. Quarantine New Object](#465-quarantine-new-object)
63+
- [5. Logging and Monitoring](#5-logging-and-monitoring)
64+
- [5.1. CloudTrail](#51-cloudtrail)
65+
- [5.2. VPC Flow Logs](#52-vpc-flow-logs)
66+
- [5.3. GuardDuty](#53-guardduty)
67+
- [5.4. Config](#54-config)
68+
- [5.5. Cloudwatch Logs](#55-cloudwatch-logs)
69+
- [5.6. SecurityHub](#56-securityhub)
8770

8871
<!-- /TOC -->
8972

‎docs/installation/installation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -513,6 +513,8 @@ Finally, while we started with a goal of delivering on the 12 guardrails, we bel
513513

514514
[action]: https://github.com/aws-samples/aws-secure-environment-accelerator/blob/master/.github/workflows/publish.yml
515515

516+
9. Note that a successful run of this workflow will automatically kick off the "Generate Documentation" workflow. That workflow may be initiated at any time manually via the GitHub Actions UI (since it is configured as a `workflow_dispatch` action).
517+
516518
---
517519

518520
[...Return to Accelerator Table of Contents](../index.md)

‎docs/toc-generation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Easy and automated ToC generation:
44

55
- Visual Studio Code Plugin - Markdown All in One - https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
66

7+
Note: The PDF engine (`pandoc/latex`) used in the `Release Documentation` action does not like deeply nested markdown lists. Accordingly, use `Depth From: 2` and `Depth to: 4` in Table of Contents generation.
8+
79
Other alternatives:
810

911
- Table of Contents can be generated for Markdown documents using the following tool: https://github.com/AlanWalk/Markdown-TOC

0 commit comments

Comments
 (0)