From 9be9391fc7e3018a609b7cbf0b850503b4e8bd71 Mon Sep 17 00:00:00 2001
From: Andrew Vaillancourt <andrew.vaillancourt@windriver.com>
Date: Thu, 27 Mar 2025 17:15:24 -0400
Subject: [PATCH] Add initial framework and SSH documentation

- Update doc/source/framework/index.rst with design principles and
  directory structure overview.
- Add doc/source/framework/ssh/index.rst for SSH infrastructure,
  including connection behavior and flow.
- Prepare structure for future SSH module-level documentation.

Change-Id: Ia8df587d0ec5c1c3c756ed630d9e9ea122e8cfcf
Signed-off-by: Andrew Vaillancourt <andrew.vaillancourt@windriver.com>
---
 doc/source/framework/index.rst     | 42 +++++++++++++++++++++++--
 doc/source/framework/ssh/index.rst | 50 ++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/framework/ssh/index.rst

diff --git a/doc/source/framework/index.rst b/doc/source/framework/index.rst
index e9334d20..ac97151e 100644
--- a/doc/source/framework/index.rst
+++ b/doc/source/framework/index.rst
@@ -2,10 +2,48 @@
 **framework/** Documentation
 ============================
 
-This section covers the **testing framework** used in StarlingX.
+The **framework/** directory contains core infrastructure for the StarlingX Test
+Automation Framework, including logging, SSH, threading, database operations,
+REST clients, runner logic, and other essential utilities that power keyword
+execution and test orchestration.
+
+Design Principles
+=================
+
+The framework layer is built for reliability, extensibility, and separation of concerns:
+
+- **Reusable building blocks**: Shared services such as SSH, threading, and logging are centralized here.
+- **Test-agnostic logic**: This layer should not depend on specific testcases or keyword domains.
+- **Isolation from test logic**: Business logic and automation commands live in `keywords/` or `testcases/`,
+  while framework components focus on supporting infrastructure.
+- **Consistent logging and error handling**: All modules use the same logger and exception patterns.
 
 --------
 Contents
 --------
 
-*(Additional framework documentation will be added here.)*
+.. toctree::
+   :maxdepth: 1
+
+   ssh/index
+
+Directory Structure
+===================
+
+An overview of the key subdirectories in **framework/**:
+
+.. code-block:: bash
+
+   framework/
+   ├── database/           # Handles test result storage and querying
+   ├── exceptions/         # Custom framework exception classes
+   ├── logging/            # Logging setup, formatting, and filtering
+   ├── pytest_plugins/     # Plugins for customizing test discovery and result capture
+   ├── resources/          # Static resources and backup files
+   ├── rest/               # REST client interfaces and response helpers
+   ├── runner/             # Scripts and objects for test execution
+   ├── scanning/           # Handles scan and upload of test artifacts
+   ├── ssh/                # SSH connections, prompts, and secure transfers
+   ├── threading/          # Multi-threading infrastructure
+   ├── validation/         # Generic input validation utilities
+   └── web/                # Web automation helpers (actions, conditions, locators)
diff --git a/doc/source/framework/ssh/index.rst b/doc/source/framework/ssh/index.rst
new file mode 100644
index 00000000..56ede714
--- /dev/null
+++ b/doc/source/framework/ssh/index.rst
@@ -0,0 +1,50 @@
+================================
+**framework/ssh/** Documentation
+================================
+
+The **framework/ssh/** directory provides SSH-related infrastructure for the
+StarlingX Test Framework. It includes utilities for establishing remote
+connections, handling interactive prompts, and performing secure file transfers.
+
+This layer is designed to be reusable across the entire framework, and abstracts
+SSH complexity away from keywords and test logic.
+
+--------
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+   :caption: SSH Modules
+
+
+Overview
+========
+
+The SSH layer encapsulates all logic related to:
+
+- **Establishing connections** (with or without jump hosts).
+- **Executing remote commands** (including interactive or sudo-based workflows).
+- **Handling prompts** using reusable response objects.
+- **Secure file transfers** using built-in Paramiko support.
+- **Cleaning up output** (e.g., removing ANSI sequences).
+
+These modules are used by keyword implementations to run system-level commands
+on remote hosts in a consistent and fault-tolerant manner.
+
+Connection Behavior
+===================
+
+The SSH connection adapts based on the test lab's setup and the type of command being executed:
+
+1. Check whether a jump host is required.
+2. If needed, connect to the jump host using Paramiko.
+3. Open a channel to the final destination (target host).
+4. Establish the SSH session to the target host.
+5. Use one of the following modes:
+
+   - ``exec_command()`` for simple non-interactive commands.
+   - ``invoke_shell()`` when prompt interaction or ``sudo`` is needed.
+
+6. Execute the command and capture output.
+7. Strip any ANSI escape sequences for cleaner parsing/logs.