[patch] Create/update documentation

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - '**'
+    tags-ignore:
+      - '**'
+  release:
+    types: [ published ]
+
+# Ensure only one build at a time for any branch, cancelling any in-progress builds
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py', '**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install package and doc build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: |
+          mkdocs build
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@4.1.7
+        if: ${{ github.event_name == 'release' || contains(github.event.head_commit.message, '[doc]') }}
+        with:
+          branch: gh-pages
+          folder: site
+
+# Made with Bob

.gitignore

@@ -19,3 +19,5 @@ venv/
 # Other
 kubectl.exe
 /build
+/.vscode
+/site

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2025-12-15T15:57:18Z",
+  "generated_at": "2025-12-25T19:13:06Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -95,6 +95,44 @@
         "verified_result": null
       }
     ],
+    "docs/cli/create-initial-users.md": [
+      {
+        "hashed_secret": "33f220dd67f717cc949db63e21c90e130a6137da",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 126,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/index.md": [
+      {
+        "hashed_secret": "33f220dd67f717cc949db63e21c90e130a6137da",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 56,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/cli/notify-slack.md": [
+      {
+        "hashed_secret": "1572c8dd915cf3bdecae817b1cb65847b4e94037",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 61,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "2d8b1074eb78b85690ced3d2cc0aed0466f6f652",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 207,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
     "src/mas/devops/templates/ibm-entitlement-dockerconfig.json.j2": [
       {
         "hashed_secret": "d2e2ab0f407e4ee3cf2ab87d61c31b25a74085e5",

bin/mas-devops-notify-slack

@@ -33,7 +33,7 @@ def _getToolchainLink() -> str:
     return ""
 
 
-def notifyProvisionFyre(channels: list[str], rc: int, additionalMsg: str = None) -> bool:
+def notifyProvisionFyre(channels: list[str], rc: int, additionalMsg: str | None = None) -> bool:
     """Send Slack notification about Fyre OCP cluster provisioning status."""
     name = _getClusterName()
     toolchainLink = _getToolchainLink()
@@ -67,7 +67,7 @@ def notifyProvisionFyre(channels: list[str], rc: int, additionalMsg: str = None)
     return response.data.get("ok", False)
 
 
-def notifyProvisionRoks(channels: list[str], rc: int, additionalMsg: str = None) -> bool:
+def notifyProvisionRoks(channels: list[str], rc: int, additionalMsg: str | None = None) -> bool:
     """Send Slack notification about ROKS cluster provisioning status."""
     name = _getClusterName()
     toolchainLink = _getToolchainLink()

docs/api/aiservice.md

@@ -0,0 +1,5 @@
+# AI Service Module
+
+The `aiservice` module provides functions for AI/ML service management and configuration.
+
+::: mas.devops.aiservice

docs/api/db2.md

@@ -0,0 +1,5 @@
+# DB2 Module
+
+The `db2` module provides functions for DB2 database configuration and validation.
+
+::: mas.devops.db2

docs/api/index.md

@@ -0,0 +1,98 @@
+# API Reference
+
+Welcome to the MAS DevOps API reference documentation. This section provides detailed documentation for all modules, classes, and functions in the `mas-devops` package.
+
+## Core Modules
+
+These modules provide fundamental operations for working with OpenShift/Kubernetes and related technologies:
+
+- **[OCP](ocp.md)**: OpenShift/Kubernetes cluster operations including namespace management, resource creation, and cluster interactions
+- **[Tekton](tekton.md)**: Pipeline management, installation, and execution of Tekton pipelines for MAS automation
+- **[OLM](olm.md)**: Operator Lifecycle Manager operations for installing and managing operators
+- **[Utils](utils.md)**: Common utility functions and helper methods used throughout the library
+
+## MAS Modules
+
+Modules specifically designed for managing Maximo Application Suite:
+
+- **[Suite](mas/suite.md)**: Core MAS suite management including installation, configuration, and lifecycle operations
+- **[Apps](mas/apps.md)**: MAS application management for deploying and configuring MAS applications like Manage, Monitor, etc.
+
+## Service Integration Modules
+
+Modules for integrating with various services and dependencies:
+
+- **[DB2](db2.md)**: Database operations including DB2 configuration validation and management
+- **[SLS](sls.md)**: Suite License Service integration for license management
+- **[AI Service](aiservice.md)**: AI/ML service management and configuration
+- **[Slack](slack.md)**: Slack notification and alerting integration
+
+## SaaS Modules
+
+Modules for SaaS-specific operations:
+
+- **[Job Cleaner](saas/job_cleaner.md)**: Utilities for cleaning up completed jobs in SaaS environments
+
+## User Management
+
+- **[Users](users.md)**: User creation and management for MAS deployments
+
+## Module Overview
+
+### Core Operations
+
+The core modules provide the foundation for all MAS DevOps operations:
+
+```python
+from mas.devops.ocp import createNamespace, getResource
+from mas.devops.tekton import installOpenShiftPipelines
+from mas.devops.olm import installOperator
+from mas.devops.utils import waitForResource
+```
+
+### MAS Management
+
+Work with MAS suite and applications:
+
+```python
+from mas.devops.mas.suite import installMAS, configureMAS
+from mas.devops.mas.apps import installApp, configureApp
+```
+
+### Service Integration
+
+Integrate with external services:
+
+```python
+from mas.devops.db2 import validateDB2Config
+from mas.devops.sls import configureSLS
+from mas.devops.slack import sendSlackNotification
+```
+
+## Navigation
+
+Use the navigation menu on the left to browse through the API documentation for each module. Each module page includes:
+
+- Module overview and purpose
+- Class and function documentation with parameters and return types
+- Usage examples
+- Related modules and cross-references
+
+## Conventions
+
+Throughout the API documentation:
+
+- **Required parameters** are clearly marked
+- **Optional parameters** include default values
+- **Return types** are specified for all functions
+- **Exceptions** that may be raised are documented
+- **Examples** demonstrate common usage patterns
+
+## Getting Help
+
+If you need help using the API:
+
+1. Check the [Quick Start Guide](../getting-started/quickstart.md) for common usage patterns
+2. Review the specific module documentation for detailed information
+3. Look at the [CLI Tools](../cli/index.md) for command-line usage examples
+4. Visit the [GitHub repository](https://github.com/ibm-mas/python-devops) to report issues or ask questions

docs/api/mas/apps.md

@@ -0,0 +1,5 @@
+# MAS Apps Module
+
+The `mas.apps` module provides functions for MAS application management.
+
+::: mas.devops.mas.apps

docs/api/mas/suite.md

@@ -0,0 +1,5 @@
+# MAS Suite Module
+
+The `mas.suite` module provides functions for MAS core suite management.
+
+::: mas.devops.mas.suite

docs/api/ocp.md

@@ -0,0 +1,5 @@
+# OCP Module
+
+The `ocp` module provides functions for interacting with OpenShift/Kubernetes clusters.
+
+::: mas.devops.ocp

docs/api/olm.md

@@ -0,0 +1,5 @@
+# OLM Module
+
+The `olm` module provides functions for managing Operator Lifecycle Manager (OLM) operations.
+
+::: mas.devops.olm

docs/api/saas/job_cleaner.md

@@ -0,0 +1,5 @@
+# SaaS Job Cleaner Module
+
+The `saas.job_cleaner` module provides utilities for cleaning up completed jobs in SaaS environments.
+
+::: mas.devops.saas.job_cleaner

docs/api/slack.md

@@ -0,0 +1,5 @@
+# Slack Module
+
+The `slack` module provides functions for Slack notification and alerting integration.
+
+::: mas.devops.slack

docs/api/sls.md

@@ -0,0 +1,5 @@
+# SLS Module
+
+The `sls` module provides functions for Suite License Service integration.
+
+::: mas.devops.sls

docs/api/tekton.md

@@ -0,0 +1,5 @@
+# Tekton Module
+
+The `tekton` module provides functions for managing Tekton pipelines in OpenShift.
+
+::: mas.devops.tekton

docs/api/users.md

@@ -0,0 +1,5 @@
+# Users Module
+
+The `users` module provides functions for user creation and management in MAS deployments.
+
+::: mas.devops.users

docs/api/utils.md

@@ -0,0 +1,5 @@
+# Utils Module
+
+The `utils` module provides common utility functions and helper methods.
+
+::: mas.devops.utils