Add Sphinx documentation setup and initial content

- Created build_docs.sh script for building documentation.
- Added requirements.txt for Sphinx and related packages.
- Configured Sphinx in conf.py with necessary extensions and settings.
- Created index.rst with project overview, installation, usage, and API documentation structure.
- Documented core components and configuration models in separate .rst files.
- Implemented autodoc for GitHubClient, TemplateManager, and data models.
- Added initial models for GitHub configuration, workflow configuration, PR configuration, and template input.
- Developed TemplateManager class for handling template rendering and configuration.
- Added Jinja2 templates for Ansible and Terraform workflows.
- Created ROADMAP.md for future IAM access rules discussion.

design-docs/README.md

@@ -1,15 +1,33 @@
-# EKS Automation Lambda Implementation Plan
+# Template Automation System Implementation Plan
 
-## Project Map
+## System Architecture
 
-### template-eks-cluster
-This is the template repo that is generated from the lambda function, we're designing this whole system to be agnostic towards which repos it's creating; this will be the first example of this style of condiguration (pattern).
+The Template Automation System is designed to be a generic, template-agnostic infrastructure that can automate the creation and configuration of any type of repository from a template. The system consists of two core components and can work with any number of template repositories.
 
-### terraform-aws-template-automation
-This is the terraform module that is repsonsible for deploying our Lambda function along with any peripheral infrastructure that may be required, such as API Gateway. If SSM parameters or Secrets are required in the lambda function, they get deployed through this module.
+### Core Components
 
-### template-automation-lambda
-This is actual Lambda function, this repo creates a Docker image that we deploy to Lambda. Our actual lambda code is in template_automation/app.py.
+#### terraform-aws-template-automation
+This is the foundational Terraform module that deploys the automation infrastructure:
+- Deploys the Lambda function and required AWS resources (API Gateway, IAM roles, etc.)
+- Manages any required SSM parameters or Secrets
+- Provides a reusable module that can be included in any AWS environment
+- Template-agnostic - works with any type of repository template
+
+#### template-automation-lambda
+This is the engine of the automation system:
+- Implements the core repository templating logic in template_automation/app.py
+- Packaged as a Docker image for Lambda deployment
+- Handles repository creation, branch management, and PR automation
+- Template-agnostic - can work with any properly structured template repository
+
+### Template Repositories
+
+#### template-eks-cluster (Example)
+This is an example template repository that demonstrates how to structure a template for use with the automation system:
+- Shows the pattern for creating EKS clusters
+- Serves as a reference implementation
+- Demonstrates best practices for template structure
+- One of many possible templates that could be used with the system
 
 ### Build Infrastructure Requirements
 The Terraform configuration in this repository is specifically for building the Lambda container image in ECR. Due to tooling restrictions and access requirements, the build process must be executed in GitHub.com rather than in the target organization's environment. This means:
@@ -20,70 +38,103 @@ The Terraform configuration in this repository is specifically for building the
 - The resulting container image is then referenced by the terraform-aws-template-automation module for actual deployment
 
 ## Overview
-This document outlines the implementation plan for enhancing the EKS Automation Lambda to improve its GitHub integration workflow and testing capabilities. Most of this work will take place in template_automation/app.py
+This document outlines the implementation plan for the Template Automation System, using an EKS cluster template as our first case study. While we'll be working with the `template-eks-cluster` repository to validate and demonstrate the system's capabilities, the core automation components (`template-automation-lambda` and `terraform-aws-template-automation`) are designed to work with any properly structured template repository.
+
+The EKS cluster template serves as an excellent first example because it:
+- Demonstrates complex configuration processing requirements
+- Shows how templates can define their own workflow automation
+- Provides a real-world validation of the system's flexibility
+- Establishes patterns that other templates can follow
+
+Most of the core automation work will take place in `template_automation/app.py`, while the EKS-specific template logic resides in the `template-eks-cluster` repository. This separation ensures that our automation system remains template-agnostic while allowing templates to define their own specialized behavior.
 
 ## Implementation Phases
 
-### Phase 1: Lambda Function Updates
-Updates to the Lambda function to improve repository management:
+### Phase 1: Lambda Function Core Updates
+Updates to the Lambda function to establish template-agnostic repository management:
 
 - **Branch Management**
-  - Create new "init-cluster" branch instead of pushing directly to main
-  - Implement branch creation in GitHub client (template_automation/app.py)
-  - Add error handling for branch operations
+  - Create new initialization branch instead of pushing directly to main
+  - Implement flexible branch creation in GitHub client (template_automation/app.py)
+  - Add robust error handling for branch operations
+  - Support template-specific branch naming (e.g., "init-cluster" for EKS templates)
 
 - **Pull Request Automation**
   - Add automatic PR creation after pushing changes
-  - Include standard PR template and description
-  - Implement PR creation in GitHub client
+  - Implement configurable PR creation logic in GitHub client
+  - Support template-specific PR templates and descriptions
+  - Allow templates to define their PR strategies
 
-### Phase 2: GitHub Actions Workflow Updates
-Clean out current github actions in template repo (template-eks-cluster).
-Enhance the GitHub Actions workflow configuration:
+### Phase 2: Template Processing Framework
+Enhance the framework for processing template repositories, using EKS template as reference:
 
-- **HCL File Generation**
-  - Add action to expand config.js into HCL files, this will be done through ansible. Review the generate_hcl_files.yml playbook.
-  - Implement Terraform plan action post-HCL generation
-  - Add validation steps for generated HCL
+- **Configuration Processing**
+  - Create flexible configuration processing system
+  - Support multiple configuration formats (JSON, HCL, YAML)
+  - Allow templates to define custom processing logic
+  - Example: Implement config.js to HCL conversion via Ansible for EKS template
+
+- **GitHub Actions Framework**
+  - Create template-agnostic workflow framework
+  - Allow templates to define custom GitHub Actions
+  - Support environment-specific configurations
+  - Example: Implement EKS template's generate_hcl_files.yml playbook
 
 - **Runner Configuration**
-  - Templateize GitHub Actions workflow files
-  - Configure runners based on AWS account IDs
-  - Add support for lab environment runners
   - Implement account-specific runner selection
+  - Support lab environment runners
+  - Configure runners based on AWS account IDs
+  - Enable template-specific validation steps
 
 ### Phase 3: Testing Implementation
-Comprehensive testing setup:
+Establish comprehensive testing framework for both core system and templates:
 
-- **Lab Environment**
+- **Lab Environment Setup**
   - Configure workflow for lab AWS account
   - Set up isolated testing environment
-  - Create test cluster configurations
+  - Create test configurations for various template types
+  - Example: Set up EKS cluster test configurations
+
+- **Core System Testing**
+  - Test template-agnostic functionality
+  - Validate GitHub integration components
+  - Test configuration processing framework
+  - Verify error handling and recovery
 
 - **End-to-End Testing**
   - Implement full workflow testing
   - Create demonstration environment
   - Add integration tests for GitHub operations
-  - Implement validation checks
+  - Test template-specific validations
+  - Example: Validate EKS cluster creation workflow
+
+### Phase 4: Documentation and Interface
+Establish documentation and support infrastructure:
 
-### Phase 4: Manual Trigger Interface
-Short-term manual operation support:
+- **Core System Documentation**
+  - Document Lambda invocation process
+  - Template structure requirements
+  - Configuration schema documentation
+  - Template processing hooks
 
-- **Documentation**
-  - Lambda invocation process
-  - Example payload templates
-  - Verification steps and checks
+- **Template Development Guide**
+  - Template structure guidelines
+  - Best practices for template design
+  - Example implementations (using EKS template)
+  - Template testing guidelines
 
 - **Future Considerations**
-  - CRF integration planning
-  - Automation transition strategy
+  - Additional template types beyond EKS
+  - Enhanced template processing capabilities
+  - Integration with other systems (e.g., CRF)
+  - Template marketplace concept
 
 ## Success Criteria
-- Lambda successfully creates branches and PRs
-- GitHub Actions properly expand config and run Terraform plans
-- Workflows correctly target different AWS accounts
-- End-to-end testing works in lab environment
-- Clear documentation exists for manual processes
+- Core automation system successfully processes any valid template
+- Templates can define their own processing logic and validation
+- Comprehensive testing framework validates both system and templates
+- Clear documentation helps users create new templates
+- System demonstrates flexibility with multiple template types
 
 ## Dependencies
 - GitHub API access and permissions

docs/build_docs.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -e
+
+# Ensure we're in the project root
+cd "$(dirname "$0")/.."
+
+# Create and activate virtual environment if it doesn't exist
+if [ ! -d "docs/venv" ]; then
+    python3 -m venv docs/venv
+fi
+source docs/venv/bin/activate
+
+# Install dependencies and package in development mode
+pip install -r docs/requirements.txt
+pip install -e .
+
+# Create documentation directories
+mkdir -p docs/source/_static
+mkdir -p docs/build
+
+# Generate documentation
+cd docs
+sphinx-build -b html source build
+
+echo "Documentation built successfully in docs/build/index.html"

docs/requirements.txt

@@ -0,0 +1,6 @@
+sphinx
+sphinx_rtd_theme
+sphinx-autodoc-typehints
+pydantic~=2.6
+boto3>=1.38.6
+requests

docs/source/conf.py

@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information -----------------------------------------------------
+project = 'Template Automation Lambda'
+copyright = '2025, Template Automation Team'
+author = 'Template Automation Team'
+release = '1.0.0'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',  # Support for Google-style docstrings
+    'sphinx.ext.viewcode',  # Add links to source code
+    'sphinx.ext.intersphinx',  # Link to other project's documentation
+    'sphinx_autodoc_typehints',  # Support for type hints
+]
+
+# -- Options for autodoc ----------------------------------------------------
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'show-inheritance': True,
+    'special-members': '__init__',
+}
+
+# Napoleon settings for Google-style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_type_aliases = None
+
+# -- Options for HTML output -------------------------------------------------
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# Intersphinx mapping
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'boto3': ('https://boto3.amazonaws.com/v1/documentation/api/latest', None),
+}

docs/source/index.rst

@@ -0,0 +1,94 @@
+Template Automation Lambda Documentation
+=====================================
+
+Welcome to the Template Automation Lambda documentation. This system provides a flexible
+template automation framework for creating and configuring repositories from templates.
+
+Quick Start
+----------
+
+The Template Automation Lambda is an AWS Lambda function that automates the process of creating
+repositories from templates. It handles:
+
+- Repository creation from templates
+- Template rendering with variable substitution
+- Pull request creation with customizable settings
+- Workflow automation triggers
+
+Installation
+-----------
+
+To install the package and its dependencies:
+
+.. code-block:: bash
+
+   pip install -r requirements.txt
+   pip install -e .
+
+Usage
+-----
+
+Basic usage example:
+
+.. code-block:: python
+
+   from template_automation.app import lambda_handler
+   
+   event = {
+       "project_name": "my-new-repo",
+       "owning_team": "devops",
+       "template_settings": {
+           "variables": {
+               "environment": "prod",
+               "region": "us-west-2"
+           }
+       }
+   }
+   
+   lambda_handler(event, {})
+
+API Documentation
+---------------
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules/github_client
+   modules/template_manager
+   modules/models
+   modules/lambda_handler
+
+Core Components
+-------------
+
+- :doc:`modules/github_client` - GitHub API interaction for repository and PR management
+- :doc:`modules/template_manager` - Template rendering and configuration handling
+- :doc:`modules/models` - Pydantic data models for input validation
+- :doc:`modules/lambda_handler` - AWS Lambda function entry point
+
+Configuration
+------------
+
+The system uses several configuration models:
+
+- **GitHubConfig**: GitHub API and authentication settings
+- **WorkflowConfig**: Template workflow configuration
+- **PRConfig**: Pull request settings
+- **TemplateInput**: Input parameters for template processing
+
+Environment Variables
+-------------------
+
+Required environment variables:
+
+- ``GITHUB_TOKEN``: GitHub Personal Access Token
+- ``GITHUB_ORG``: GitHub Organization name
+- ``TEMPLATE_REPO``: Template repository name
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/modules/github_client.rst

@@ -0,0 +1,16 @@
+GitHub Client
+=============
+
+.. automodule:: template_automation.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GitHubClient Class
+----------------
+
+.. autoclass:: template_automation.app.GitHubClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__

docs/source/modules/lambda_handler.rst

@@ -0,0 +1,7 @@
+Lambda Handler
+=============
+
+.. automodule:: template_automation.app
+   :members: lambda_handler, operate_github, generate_repository_name, get_parameter
+   :undoc-members:
+   :show-inheritance: