Adding skeleton for docs-as-code

jaymccon · jaymccon · commit b359b10001e3 · 2020-10-12T11:57:42.000-07:00
diff --git a/.github/workflows/main-docs-build.yml b/.github/workflows/main-docs-build.yml
@@ -0,0 +1,38 @@
+name: main-documentation
+
+on:
+  push:
+    branches:
+    - master
+    - main
+jobs:
+  build-adocs:
+    runs-on: ubuntu-18.04
+    name: asciidoc builder
+    steps:
+    - name: Checkout (main)
+      uses: actions/checkout@v2
+    - name: Get new doc updates
+      run: |
+           wget https://raw.githubusercontent.com/aws-quickstart/quickstart-documentation-base-common/main/.utils/configure_git_env.sh
+           chmod +x configure_git_env.sh
+           ./configure_git_env.sh
+    - name: Setup python
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.x
+    - name: Generate dynamic content.
+      run: ./docs/boilerplate/.utils/generate_dynamic_content.sh
+    - name: Run local actions
+      id: adoc
+      uses: ./docs/boilerplate/.actions/asciidoctor-action
+      with:
+        program: "./docs/boilerplate/.utils/build_docs.sh"
+    - name: Stage and Push changes to gh-pages branch.
+      run: ./docs/boilerplate/.utils/commit_and_push_to_ghpages.sh
+      env:
+        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+    - name: Configure gh-pages source and trigger build if necessary.
+      run: ./docs/boilerplate/.utils/config_and_trigger_gh-pages.sh
+      env:
+        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "docs/boilerplate"]
+	path = docs/boilerplate
+	url = https://github.com/aws-quickstart/quickstart-documentation-base-common.git
diff --git a/.nojekyll b/.nojekyll
diff --git a/docs/boilerplate b/docs/boilerplate
@@ -0,0 +1 @@
+Subproject commit 7ce4ed52ce805c34ad504b8ef1eee597a31c729a
diff --git a/docs/generated/parameters/index.adoc b/docs/generated/parameters/index.adoc
@@ -0,0 +1 @@
+// placeholder
diff --git a/docs/generated/regions/index.adoc b/docs/generated/regions/index.adoc
@@ -0,0 +1 @@
+// placeholder
diff --git a/docs/generated/services/index.adoc b/docs/generated/services/index.adoc
@@ -0,0 +1 @@
+// placeholder
diff --git a/docs/generated/services/metadata.adoc b/docs/generated/services/metadata.adoc
@@ -0,0 +1 @@
+// placeholder
diff --git a/docs/images/architecture_diagram.png b/docs/images/architecture_diagram.png
diff --git a/docs/images/aws-quickstart-graphic.png b/docs/images/aws-quickstart-graphic.png
diff --git a/docs/images/cfn_outputs.png b/docs/images/cfn_outputs.png
diff --git a/docs/partner_editable/_settings.adoc b/docs/partner_editable/_settings.adoc
@@ -0,0 +1,27 @@
+// Do not change this first attribute. Do change the others.
+:quickstart-team-name: AWS Quick Start team
+:quickstart-project-name: quickstart-documentation-base
+:partner-product-name: Example Product Name
+// For the following attribute, if you have no short name, enter the same name as partner-product-name.
+:partner-product-short-name: Example Product Name
+// If there's no partner, comment partner-company-name and partner-contributors.
+:partner-company-name: Example Company Name, Ltd.
+:doc-month: Month of launch or significant update (spelled out)
+:doc-year: Year
+// For the following two "contributor" attributes, if the partner agrees to include names in the byline, 
+// enter names for both partner-contributors and quickstart-contributors. 
+// Otherwise, delete all placeholder names: everything preceding "{partner-company-name}"  
+// and "{quickstart-team-name}". Use commas as shown in the placeholder text. 
+// Use the comma before "and" only when three or more names.
+:partner-contributors: Shuai Ye, Michael McConnell, and John Smith, {partner-company-name}
+:quickstart-contributors: Toni Jones, {quickstart-team-name}
+// For deployment_time, use minutes if deployment takes an hour or less, 
+// for example, 30 minutes or 60 minutes. 
+// Use hours for deployment times greater than 60 minutes (rounded to a quarter hour),
+// for example, 1.25 hours, 2 hours, 2.5 hours.
+:deployment_time: 15 minutes / 60 minutes / 1.5 hours
+:default_deployment_region: us-east-1
+// Uncomment the following two attributes if you are using an AWS Marketplace listing.
+// Additional content will be generated automatically based on these attributes.
+// :marketplace_subscription:
+// :marketplace_listing_url: https://example.com/
diff --git a/docs/partner_editable/additional_info.adoc b/docs/partner_editable/additional_info.adoc
@@ -0,0 +1,23 @@
+// Add steps as necessary for accessing the software, post-configuration, and testing. Don’t include full usage instructions for your software, but add links to your product documentation for that information.
+//Should any sections not be applicable, remove them
+
+== Test the deployment
+// If steps are required to test the deployment, add them here. If not, remove the heading
+
+== Post deployment steps
+// If Post-deployment steps are required, add them here. If not, remove the heading
+
+== Best practices for using {partner-product-short-name} on AWS
+// Provide post-deployment best practices for using the technology on AWS, including considerations such as migrating data, backups, ensuring high performance, high availability, etc. Link to software documentation for detailed information.
+
+_Add any best practices for using the software._
+
+== Security
+// Provide post-deployment best practices for using the technology on AWS, including considerations such as migrating data, backups, ensuring high performance, high availability, etc. Link to software documentation for detailed information.
+
+_Add any security-related information._
+
+== Other useful information
+//Provide any other information of interest to users, especially focusing on areas where AWS or cloud usage differs from on-premises usage.
+
+_Add any other details that will help the customer use the software on AWS._
diff --git a/docs/partner_editable/architecture.adoc b/docs/partner_editable/architecture.adoc
@@ -0,0 +1,28 @@
+Deploying this Quick Start for a new virtual private cloud (VPC) with
+default parameters builds the following {partner-product-short-name} environment in the
+AWS Cloud.
+
+// Replace this example diagram with your own. Send us your source PowerPoint file. Be sure to follow our guidelines here : http://(we should include these points on our contributors giude)
+:xrefstyle: short
+[#architecture1]
+.Quick Start architecture for {partner-product-short-name} on AWS
+[link=images/architecture_diagram.png]
+image::../images/architecture_diagram.png[Architecture,width=100%,height=100%]
+
+As shown in <<architecture1>>, the Quick Start sets up the following:
+
+* A highly available architecture that spans two Availability Zones.*
+* A VPC configured with public and private subnets, according to AWS
+best practices, to provide you with your own virtual network on AWS.*
+* In the public subnets:
+** Managed network address translation (NAT) gateways to allow outbound
+internet access for resources in the private subnets.*
+** A Linux bastion host in an Auto Scaling group to allow inbound Secure
+Shell (SSH) access to EC2 instances in public and private subnets.*
+* In the private subnets:
+** <item>.
+** <item>.
+// Add bullet points for any additional components that are included in the deployment. Make sure that the additional components are also represented in the architecture diagram. End each bullet with a period.
+* <describe any additional components>.
+
+[.small]#*The template that deploys the Quick Start into an existing VPC skips the components marked by asterisks and prompts you for your existing VPC configuration.#
diff --git a/docs/partner_editable/deploy_steps.adoc b/docs/partner_editable/deploy_steps.adoc
@@ -0,0 +1,54 @@
+// We need to work around Step numbers here if we are going to potentially exclude the AMI subscription
+=== Sign in to your AWS account
+
+. Sign in to your AWS account at https://aws.amazon.com with an IAM user role that has the necessary permissions. For details, see link:#_planning_the_deployment[Planning the deployment] earlier in this guide.
+. Make sure that your AWS account is configured correctly, as discussed in the link:#_technical_requirements[Technical requirements] section.
+
+// Optional based on Marketplace listing. Not to be edited
+ifdef::marketplace_subscription[]
+=== Subscribe to the {partner-product-short-name} AMI
+
+This Quick Start requires a subscription to the AMI for {partner-product-short-name} in AWS Marketplace.
+
+. Sign in to your AWS account.
+. {marketplace_listing_url}[Open the page for the {partner-product-short-name} AMI in AWS Marketplace], and then choose *Continue to Subscribe*.
+. Review the terms and conditions for software usage, and then choose *Accept Terms*. +
+  A confirmation page loads, and an email confirmation is sent to the account owner. For detailed subscription instructions, see the https://aws.amazon.com/marketplace/help/200799470[AWS Marketplace documentation^].
+
+. When the subscription process is complete, exit out of AWS Marketplace without further action. *Do not* provision the software from AWS Marketplace—the Quick Start deploys the AMI for you.
+endif::marketplace_subscription[]
+// \Not to be edited
+
+=== Launch the Quick Start
+
+NOTE: You are responsible for the cost of the AWS services used while running this Quick Start reference deployment. There is no additional cost for using this Quick Start. For full details, see the pricing pages for each AWS service used by this Quick Start. Prices are subject to change.
+
+. Sign in to your AWS account, and choose one of the following options to launch the AWS CloudFormation template. For help with choosing an option, see link:#_deployment_options[deployment options] earlier in this guide.
+
+[cols=2*]
+|===
+^|http://qs_launch_link[Deploy {partner-product-short-name} into a new VPC on AWS^]
+^|http://qs_template_link[View template^]
+
+^|http://qs_launch_link[Deploy {partner-product-short-name} into an existing VPC on AWS^]
+^|http://qs_template_link[View template^]
+|===
+
+// Adapt the following warning to your Quick Start.
+WARNING: If you’re deploying {partner-product-short-name} into an existing VPC, make sure that your VPC has two private subnets in different Availability Zones for the workload instances, and that the subnets aren’t shared. This Quick Start doesn’t support https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html[shared subnets^]. These subnets require https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html[NAT gateways^] in their route tables, to allow the instances to download packages and software without exposing them to the internet. Also make sure that the domain name option in the DHCP options is configured as explained in http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_DHCP_Options.html[DHCP options sets^]. You provide your VPC settings when you launch the Quick Start.
+
+Each deployment takes about {deployment_time} to complete.
+
+[start=2]
+. Check the AWS Region that’s displayed in the upper-right corner of the navigation bar, and change it if necessary. This is where the network infrastructure for {partner-product-short-name} will be built. The template is launched in the {default_deployment_region} Region by default.
+
+// *Note:* This deployment includes Amazon EFS, which isn’t currently supported in all AWS Regions. For a current list of supported Regions, see the https://docs.aws.amazon.com/general/latest/gr/elasticfilesystem.html[endpoints and quotas webpage].
+
+[start=3]
+. On the *Create stack* page, keep the default setting for the template URL, and then choose *Next*.
+. On the *Specify stack details* page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary.
+
+// In the following tables, parameters are listed by category and described separately for the two deployment options:
+
+// * Parameters for deploying {partner-product-short-name} into a new VPC
+// * Parameters for deploying {partner-product-short-name} into an existing VPC
diff --git a/docs/partner_editable/deployment_options.adoc b/docs/partner_editable/deployment_options.adoc
@@ -0,0 +1,8 @@
+// Edit this placeholder text to accurately describe your architecture.
+
+This Quick Start provides two deployment options:
+
+* *Deploy {partner-product-short-name} into a new VPC*. This option builds a new AWS environment consisting of the VPC, subnets, NAT gateways, security groups, bastion hosts, and other infrastructure components. It then deploys {partner-product-short-name} into this new VPC.
+* *Deploy {partner-product-short-name} into an existing VPC*. This option provisions {partner-product-short-name} in your existing AWS infrastructure.
+
+The Quick Start provides separate templates for these options. It also lets you configure Classless Inter-Domain Routing (CIDR) blocks, instance types, and {partner-product-short-name} settings, as discussed later in this guide.
diff --git a/docs/partner_editable/faq_troubleshooting.adoc b/docs/partner_editable/faq_troubleshooting.adoc
@@ -0,0 +1,21 @@
+// Add any tips or answers to anticipated questions. This could include the following troubleshooting information. If you don’t have any other Q&A to add, change “FAQ” to “Troubleshooting.”
+
+== FAQ
+
+*Q.* I encountered a *CREATE_FAILED* error when I launched the Quick Start.
+
+*A.* If AWS CloudFormation fails to create the stack, we recommend that you relaunch the template with *Rollback on failure* set to *Disabled*. (This setting is under *Advanced* in the AWS CloudFormation console, *Options* page.) With this setting, the stack’s state is retained and the instance is left running, so you can troubleshoot the issue. (For Windows, look at the log files in %ProgramFiles%\Amazon\EC2ConfigService and C:\cfn\log.)
+// If you’re deploying on Linux instances, provide the location for log files on Linux, or omit this sentence.
+
+WARNING: When you set *Rollback on failure* to *Disabled*, you continue to incur AWS charges for this stack. Please make sure to delete the stack when you finish troubleshooting.
+
+For additional information, see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/troubleshooting.html[Troubleshooting AWS CloudFormation^] on the AWS website.
+
+*Q.* I encountered a size limitation error when I deployed the AWS CloudFormation templates.
+
+*A.* We recommend that you launch the Quick Start templates from the links in this guide or from another S3 bucket. If you deploy the templates from a local copy on your computer or from a location other than an S3 bucket, you might encounter template size limitations. For more information about AWS CloudFormation quotas, see the http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html[AWS documentation^].
+
+
+== Troubleshooting
+
+<Steps for troubleshooting the deployment go here.>
diff --git a/docs/partner_editable/licenses.adoc b/docs/partner_editable/licenses.adoc
@@ -0,0 +1,13 @@
+// Include details about the license and how they can sign up. If no license is required, clarify that. 
+
+These two paragraphs provide an example of the details you can provide. Provide links as appropriate.
+
+
+Example content below:
+
+_<license information>This Quick Start requires a license for {partner-product-short-name}. To use the Quick Start in your production environment, sign up for a license at <link>. When you launch the Quick Start, place the license key in an S3 bucket and specify its location._
+
+_If you don’t have a license, the Quick Start deploys with a trial license. The trial license gives you <n> days of free usage in a non-production environment. After this time, you can upgrade to a production license by following the instructions at <link>._
+
+// Or, if the deployment uses an AMI, update this paragraph. If it doesn’t, remove the paragraph.
+_<AMI information>The Quick Start requires a subscription to the Amazon Machine Image (AMI) for {partner-product-short-name}, which is available from https://aws.amazon.com/marketplace/[AWS Marketplace^]. Additional pricing, terms, and conditions may apply. For instructions, see link:#step-2.-subscribe-to-the-software-ami[step 2] in the deployment section._
diff --git a/docs/partner_editable/overview_target_and_usage.adoc b/docs/partner_editable/overview_target_and_usage.adoc
@@ -0,0 +1,7 @@
+// Replace the content in <>
+// Identify your target audience and explain how/why they would use this Quick Start.
+//Avoid borrowing text from third-party websites (copying text from AWS service documentation is fine). Also, avoid marketing-speak, focusing instead on the technical aspect.
+
+This guide provides instructions for deploying the {partner-product-short-name} Quick Start reference architecture on the AWS Cloud.
+
+This Quick Start is for users who <target audience and usage scenario>
diff --git a/docs/partner_editable/pre-reqs.adoc b/docs/partner_editable/pre-reqs.adoc
@@ -0,0 +1,13 @@
+// If no preperation is required, remove all content from here
+
+==== Prepare your AWS account
+
+_Describe any setup required in the AWS account prior to template launch_
+
+==== Prepare your {partner-company-name} account
+
+_Describe any setup required in the partner portal/account prior to template launch_
+
+==== Prepare for the deployment
+
+_Describe any preparation required to complete the product build, such as obtaining licenses or placing files in S3_
diff --git a/docs/partner_editable/product_description.adoc b/docs/partner_editable/product_description.adoc
@@ -0,0 +1,5 @@
+// Replace the content in <>
+// Briefly describe the software. Use consistent and clear branding. 
+// Include the benefits of using the software on AWS, and provide details on usage scenarios.
+
+<Describe how the software works on AWS.>
diff --git a/docs/partner_editable/regions.adoc b/docs/partner_editable/regions.adoc
@@ -0,0 +1,4 @@
+The following Regions are currently supported by this Quick Start.
+
+- _us-east-1 (N. Virginia)_ (EXAMPLE)
+- _us-east-2 (Ohio)_ (EXAMPLE)
diff --git a/docs/partner_editable/service_limits.adoc b/docs/partner_editable/service_limits.adoc
@@ -0,0 +1,14 @@
+// Replace the <n> in each row to specify the number of resources used in this deployment. Remove the rows for resources that aren’t used.
+|===
+|Resource |This deployment uses
+
+// Space needed to maintain table headers
+|VPCs |<n>
+|Elastic IP addresses |<n>
+|AWS Identity and Access Management (IAM) security groups |<n>
+|IAM roles |<n>
+|Auto Scaling groups |<n>
+|Application Load Balancers |<n>
+|Network Load Balancers |<n>
+|<type> instances |<n>
+|===
diff --git a/docs/partner_editable/specialized_knowledge.adoc b/docs/partner_editable/specialized_knowledge.adoc
@@ -0,0 +1,6 @@
+// Replace the content in <>
+// Describe or link to specific knowledge requirements; for example: “familiarity with basic concepts in the areas of networking, database operations, and data encryption” or “familiarity with <software>.”
+
+This Quick Start assumes familiarity with <knowledge expectations>.
+
+

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[submodule "docs/boilerplate"]`
	`2`	`+ path = docs/boilerplate`
	`3`	`+ url = https://github.com/aws-quickstart/quickstart-documentation-base-common.git`