adding read the docs

README.md

@@ -1,4 +1,4 @@
-## AWS Service Catalog Puppet Framework
+## servicecatalog-puppet
 
 ![logo](./docs/logo.png) 
 
@@ -7,88 +7,8 @@ accounts. The framework works through your lists, dedupes and spots collisions a
 AWS accounts for you. It handles the Portfolio sharing, its acceptance and can provision products cross account and cross 
 region.
 
-### High level architecture diagram
+Read the docs here: https://aws-service-catalog-puppet.readthedocs.io/en/latest/
 
-![whatisthis](./docs/whatisthis.png)
-
-This is a framework where you list your AWS accounts with tags and your AWS Service Catalog products with tags or 
-target accounts.  The framework works through your lists, dedupes and spots collisions and then provisions the products
-into your AWS accounts for you.  It handles the Portfolio sharing, its acceptance and can provision products cross account
-and cross region.
-
-## Getting started
-
-Follow the steps below to get started:
-
-### Install the tool
-Optional, but recommended:
-```bash
-virtualenv --python=python3.7 venv
-source venv/bin/activate
-```
-
-Install the package:
-```bash
-pip install aws-service-catalog-puppet
-```
-
-### Bootstrap your account
-Set up your spoke accounts:
-```bash
-servicecatalog-puppet bootstrap-spoke <MASTER_ACCOUNT_ID>
-```
-
-### Bootstrap your account
-
-There are two parts to bootstrapping the puppet.  The first is concerned with setting the global configurations.  To do 
-this we use AWS SSM Parameters.  To get setup you need to create a configuration file with a list of regions you want to 
-use - for example config.yaml:
-
-```yaml
-regions: [
-  'us-east-2',
-  'us-east-1',
-  'us-west-1',
-  'us-west-2',
-  'ap-south-1',
-  'ap-northeast-2',
-  'ap-southeast-1',
-  'ap-southeast-2',
-  'ap-northeast-1',
-  'ca-central-1',
-  'eu-central-1',
-  'eu-west-1',
-  'eu-west-2',
-  'eu-west-3',
-  'sa-east-1',
-]
-```
-Once you have this file you need to upload the config:
-```bash
-servicecatalog-puppet upload-config config.yaml
-```
-
-If you make changes to this you will need to run upload-config and bootstrap commands again for the changes to occur.
-
-Once that has completed you are ready to bring up the rest of the puppet.
-
-Create the AWS CodeCommit repo and AWS CodePipeline resources to run the puppet for your 
-master account:
-```bash
-servicecatalog-puppet bootstrap
-```
-
-### Setup your puppet
-Clone the configuration repo and configure your factory:
-```bash
-git clone --config 'credential.helper=!aws codecommit credential-helper $@' --config 'credential.UseHttpPath=true' https://git-codecommit.eu-west-1.amazonaws.com/v1/repos/ServiceCatalogPuppet
-servicecatalog-puppet seed simple ServiceCatalogPuppet
-cd ServiceCatalogPuppet
-git add .
-git commit -am "initial add"
-git push
-```
-Wait for pipeline to complete and you have a working puppet.
 
 ## License
 

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 93db8a4a90e449d3c725debb740235d5
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/index.rst.txt

@@ -0,0 +1,20 @@
+Welcome to aws-service-catalog-puppets's documentation!
+=======================================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+   :glob:
+
+   puppet/what_is_this
+   puppet/getting_up_and_running
+   puppet/designing_your_manifest
+   puppet/diving_into_the_pipeline
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/build/html/_sources/puppet/designing_your_manifest.md.txt

@@ -0,0 +1,91 @@
+Designing your manifest
+=======================
+
+## Purpose of the manifest file
+The manifest file is there to describe what you want to provision and into which accounts you want to provision products
+into.  It is possible to use AWS Organizations to make your manifest file more concise and easier to work with but the
+premise is the same - it is just a list of accounts and AWS Service Catalog products.
+
+
+## Sections of the manifest file
+There are three sections to a manifest file - the global parameters, the accounts list and the launches.  Each of the 
+three are described in the following sections.
+
+### Parameters
+
+It is possible to specify global parameters that should be used when provisioning your AWS Service Catalog Products.
+You can set the value to an explicit value or you can set the value to the result of a function call - using funcation 
+calls to set parameter values is known as using a macro.
+
+Here is an example of a simple parameter:
+```yaml
+schema: puppet-2019-04-01
+
+parameters:
+    CloudTrailLoggingBucketName:
+      default: cloudtrail-logs-for-aws
+```
+Whenever Puppet provisions a product it checks the parameters for the product.  If it sees the name match one of the 
+parameter values it will use it.  In order to avoid clashes with parameter names we recommend using descriptive names 
+like in the example - using the parameter names like ```BucketName``` will lead you into trouble pretty quickly.  
+
+#### Macros 
+You can also use a macro to set the value of a parameter.  It works in the same way as a normal parameter except it 
+executes a function to get the value first.  Here is an an example:
+```yaml
+schema: puppet-2019-04-01
+
+parameters:
+    AllAccountIds:
+      macro: 
+        method: get_accounts_for_path
+        args: /
+```
+
+At the moment there are the following macros supported:
+
+```eval_rst
++------------------------+------------------------------+----------------------------------------------+ 
+| macro method name      | args                         | description                                  |
++========================+==============================+==============================================+ 
+| get_accounts_for_path  | ou path to get accounts for  | Returns a comma seperated list of account ids|
++------------------------+------------------------------+----------------------------------------------+
+```
+
+### Accounts
+Description coming soon
+
+### Launches
+Description coming soon
+
+### Example
+```yaml
+schema: puppet-2019-04-01
+
+accounts:
+  - account_id: '<YOUR_ACCOUNT_ID>'
+    name: '<YOUR_ACCOUNT_NAME>'
+    default_region: us-east-1
+    regions_enabled:
+      - us-east-1
+      - us-west-2
+    tags:
+      - type:prod
+      - partition:us
+      - scope:pci
+
+launches:
+  account-iam-for-prod:
+    portfolio: example-simple-central-it-team-portfolio
+    product: account-iam
+    version: v1
+    parameters:
+      RoleName:
+        default: DevAdmin
+      Path:
+        default: /human-roles/
+    deploy_to:
+      tags:
+        - tag: type:prod
+          regions: default_region
+```

docs/build/html/_sources/puppet/getting_up_and_running.md.txt

@@ -0,0 +1,93 @@
+Getting up and running
+======================
+
+ServiceCatalog-Puppet runs in your AWS Account.  In order for you to install it into your account you can use the 
+aws-service-catalog-puppet cli.  This is distributed via [PyPi](https://pypi.org/project/aws-service-catalog-puppet/)
+
+## Before you install
+You should consider which account will be the home for your puppet.  This account will contain the AWS CodePipelines
+and will need to be accessible to any accounts you would like to share with.  If you are using ServiceCatalog-Factory,
+we recommend you install both tools into the same account. 
+
+
+## Installing the tool
+This is a python cli built using Python 3.
+
+It is good practice to install Python libraries in isolated environments.  You can create the a virtual environment using
+the following command:
+
+```bash
+virtualenv --python=python3.7 venv
+source venv/bin/activate
+```
+
+Once you have decided where to install the library you can install the package:
+```bash
+pip install aws-service-catalog-puppet
+```
+
+This will install the library and all of the dependencies.
+
+## Setting it up
+The Puppet will run in your account and needs some configuration.  You will need to stand up the puppet and set up the 
+configuration for it to run smoothly.
+
+You will also need to provision an IAM Role within the _spoke_ accounts - those you want to provision products in.
+
+### Bootstrap your spokes
+Set up your spoke accounts:
+```bash
+servicecatalog-puppet bootstrap-spoke <ACCOUNT_ID_OF_YOUR_PUPPET>
+```
+
+### Bootstrap your account
+
+There are two parts to bootstrapping the puppet.  The first is concerned with setting the global configurations.  To do 
+this we use AWS SSM Parameters.  To get setup you need to create a configuration file with a list of regions you want to 
+use - for example config.yaml:
+
+```yaml
+regions: [
+  'us-east-2',
+  'us-east-1',
+  'us-west-1',
+  'us-west-2',
+  'ap-south-1',
+  'ap-northeast-2',
+  'ap-southeast-1',
+  'ap-southeast-2',
+  'ap-northeast-1',
+  'ca-central-1',
+  'eu-central-1',
+  'eu-west-1',
+  'eu-west-2',
+  'eu-west-3',
+  'sa-east-1',
+]
+```
+Once you have this file you need to upload the config:
+```bash
+servicecatalog-puppet upload-config config.yaml
+```
+
+If you make changes to this you will need to run upload-config and bootstrap commands again for the changes to occur.
+
+Once that has completed you are ready to bring up the rest of the puppet.
+
+Create the AWS CodeCommit repo and AWS CodePipeline resources to run the puppet for your 
+master account:
+```bash
+servicecatalog-puppet bootstrap
+```
+
+### Setup your puppet
+Clone the configuration repo and configure your factory:
+```bash
+git clone --config 'credential.helper=!aws codecommit credential-helper $@' --config 'credential.UseHttpPath=true' https://git-codecommit.eu-west-1.amazonaws.com/v1/repos/ServiceCatalogPuppet
+servicecatalog-puppet seed simple ServiceCatalogPuppet
+cd ServiceCatalogPuppet
+git add .
+git commit -am "initial add"
+git push
+```
+Wait for pipeline to complete and you have a working puppet.

docs/build/html/_sources/puppet/what_is_this.md.txt

@@ -0,0 +1,15 @@
+What is this?
+=============
+
+This is a framework where you list your AWS accounts with tags and your AWS Service Catalog products with tags or target
+accounts. The framework works through your lists, dedupes and spots collisions and then provisions the products into your 
+AWS accounts for you. It handles the Portfolio sharing, its acceptance and can provision products cross account and cross 
+region.
+
+
+### High level architecture diagram
+
+![](./whatisthis.png)
+
+You use an AWS CodeBuild project in a central _hub_ account that provisions AWS Service Catalog Products into _spoke_
+accounts on your behalf.  The framework takes care of cross account sharing and cross region product replication for you.