Add GitHub Pages documentation site

.gitignore

@@ -34,3 +34,8 @@ kuttl-report-openstack-lightspeed.xml
 
 # Vulnerability scan output
 vuln_output.json
+
+# Sphinx docs build artifacts
+/docs/_build
+/docs/.venv
+__pycache__/

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

Makefile

@@ -430,3 +430,30 @@ catalog-build: opm ## Build a catalog image.
 .PHONY: catalog-push
 catalog-push: ## Push a catalog image.
 	$(MAKE) docker-push IMG=$(CATALOG_IMG)
+
+##@ Documentation
+
+DOCS_VENV = docs/.venv
+DOCS_PYTHON = $(DOCS_VENV)/bin/python
+
+.PHONY: .docs-venv
+.docs-venv:
+	if ! command -v python3 > /dev/null; then \
+	echo "python3 not found. Install Python 3 to build the docs."; \
+	exit 1; \
+	fi
+	test -d $(DOCS_VENV) || python3 -m venv $(DOCS_VENV)
+	$(DOCS_PYTHON) -m pip install --quiet --upgrade pip
+	$(DOCS_PYTHON) -m pip install --quiet -r docs/requirements.txt
+
+.PHONY: docs
+docs: .docs-venv ## Build docs (Sphinx, matching the Read the Docs build)
+	$(DOCS_VENV)/bin/sphinx-build -W -b html docs docs/_build/html
+
+.PHONY: docs-preview
+docs-preview: docs ## Build docs and open them in a browser
+	open docs/_build/html/index.html || xdg-open docs/_build/html/index.html
+
+.PHONY: docs-clean
+docs-clean: ## Remove built docs
+	rm -rf docs/_build

docs/conf.py

@@ -0,0 +1,12 @@
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+project = "OpenStack Lightspeed Operator"
+copyright = "OpenStack Lightspeed contributors"
+author = "OpenStack Lightspeed contributors"
+
+extensions = ["sphinxcontrib.mermaid"]
+
+exclude_patterns = ["_build", ".venv", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"

docs/configuration.rst

@@ -0,0 +1,200 @@
+Configuration
+=============
+
+Everything is configured through the ``OpenStackLightspeed`` custom
+resource (``lightspeed.openstack.org/v1beta1``). This page documents every
+field in its ``spec``.
+
+Core fields
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 10 70
+
+   * - Field
+     - Required
+     - Description
+   * - ``llmEndpoint``
+     - Yes
+     - URL of the LLM endpoint (e.g. ``https://api.openai.com/v1``). Must
+       start with ``http://`` or ``https://``.
+   * - ``llmEndpointType``
+     - Yes
+     - Provider type. See :ref:`supported-providers`.
+   * - ``modelName``
+     - Yes
+     - Model name to use at ``llmEndpoint``.
+   * - ``llmCredentials``
+     - Yes
+     - ``Secret`` name (same namespace) with the API token under key
+       ``apitoken``.
+   * - ``tlsCACertBundle``
+     - No
+     - ``ConfigMap`` name (same namespace) with a CA bundle, for
+       self-signed endpoints.
+   * - ``maxTokensForResponse``
+     - No
+     - Max response tokens. Minimum ``1``. Defaults to ``2048``.
+   * - ``llmProjectID``
+     - No
+     - Required by some providers (e.g. WatsonX).
+   * - ``llmDeploymentName``
+     - No
+     - Required by some providers (e.g. Azure OpenAI).
+   * - ``llmAPIVersion``
+     - No
+     - Required by some providers (e.g. Azure OpenAI).
+   * - ``feedbackEnabled``
+     - No
+     - User feedback collection. Defaults to ``true``.
+   * - ``transcriptsEnabled``
+     - No
+     - Conversation transcript collection. Defaults to ``false``.
+
+.. _supported-providers:
+
+Supported LLM providers (``llmEndpointType``)
+------------------------------------------------
+
+* ``openai`` — OpenAI-compatible endpoints (Ollama, vLLM, etc.)
+* ``azure_openai`` — Azure OpenAI (needs ``llmDeploymentName``, ``llmAPIVersion``)
+* ``watsonx`` — IBM watsonx.ai (needs ``llmProjectID``)
+* ``rhoai_vllm`` — vLLM via Red Hat OpenShift AI
+* ``rhelai_vllm`` — vLLM via RHEL AI
+* ``gemini`` — Google Gemini
+
+.. tip::
+
+   This list is enforced by the CRD schema and grows over time. Check
+   ``oc explain openstacklightspeed.spec.llmEndpointType`` on your cluster
+   for the current, authoritative list.
+
+Logging (``logging``)
+-----------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Field
+     - Default
+     - Description
+   * - ``logging.ogxLogLevel``
+     - ``all=info``
+     - llama-stack/OGX container. Standard level, or
+       ``component=level`` pairs (e.g. ``core=debug,providers=info``).
+   * - ``logging.lightspeedStackLogLevel``
+     - ``INFO``
+     - lightspeed-service-api container. ``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``.
+   * - ``logging.dataverseExporterLogLevel``
+     - ``INFO``
+     - Feedback/transcript exporter sidecar. Same values as above.
+   * - ``logging.postgresLogLevel``
+     - ``INFO``
+     - PostgreSQL container. ``DEBUG`` also logs every SQL statement.
+
+Persistent storage (``database``)
+------------------------------------
+
+Omit for an ``emptyDir`` volume (data lost on pod reschedule), or set to
+provision a PVC:
+
+.. code-block:: yaml
+
+   spec:
+     database:
+       size: "5Gi"                # default: 1Gi
+       class: "my-storage-class"  # default: cluster's default StorageClass
+
+Container resources (``resources``)
+--------------------------------------
+
+Every container has a default request/limit. Setting one replaces its
+default entirely:
+
+.. code-block:: yaml
+
+   spec:
+     resources:
+       llamaStack:
+         requests: {cpu: "500m", memory: "2Gi"}
+         limits: {cpu: "2", memory: "8Gi"}
+       lightspeedService:
+         requests: {cpu: "250m", memory: "512Mi"}
+         limits: {cpu: "1", memory: "2Gi"}
+       postgres:
+         requests: {cpu: "30m", memory: "300Mi"}
+         limits: {cpu: "500m", memory: "2Gi"}
+       okp:
+         requests: {cpu: "500m", memory: "2Gi"}
+         limits: {cpu: "2", memory: "4Gi"}
+       consolePlugin:
+         requests: {cpu: "50m", memory: "64Mi"}
+         limits: {cpu: "200m", memory: "256Mi"}
+       mcp:
+         requests: {cpu: "50m", memory: "64Mi"}
+         limits: {memory: "200Mi"}
+
+.. _offline-knowledge-portal:
+
+Offline Knowledge Portal (``okp``)
+--------------------------------------
+
+.. important::
+
+   OKP is deployed on **every** install — ``spec.okp`` configures it, it
+   doesn't gate whether it's deployed. Pulling its image needs the same
+   free ``registry.redhat.io`` account as :ref:`redhat-registry-access`.
+
+.. code-block:: yaml
+
+   spec:
+     okp: {}   # no access key: browsing works, search doesn't
+
+.. code-block:: yaml
+
+   spec:
+     okp:
+       accessKey: okp-access-key-secret   # Secret key: "access_key"
+
+* **No ``accessKey``** (default) — browse docs and product lifecycle
+  content; no search, Solutions, or Articles. What upstream users run on.
+* **With ``accessKey``** — full search and the encrypted knowledgebase.
+  Needs an active Red Hat Satellite subscription (`get one
+  <https://access.redhat.com/offline/access>`_) — a bonus if you already
+  have one, not something every user needs.
+
+By default, **RAG grounding is OKP-only** — the bundled community
+documentation is disabled unless you set ``dev.okpRagOnly: false`` (below).
+
+Developer / experimental options (``dev``)
+-----------------------------------------------
+
+.. warning::
+
+   Not part of the stable API — may change without notice.
+
+.. code-block:: yaml
+
+   spec:
+     dev:
+       featureFlags:
+         - rhoso_mcps   # enables the read-only MCP introspection sidecar
+       okpChunkFilterQuery: "product:(*openstack* OR *openshift*)"  # example override
+       okpRagOnly: false  # include bundled community docs too, not just OKP
+       rhosMCPConfig: |
+         debug: true
+         workers: 4
+
+* ``okpChunkFilterQuery`` and ``okpRagOnly`` take effect immediately, with
+  no ``featureFlags`` entry needed — they're independent of
+  ``rhoso_mcps``. If unset, ``okpChunkFilterQuery`` auto-detects your
+  OpenShift/RHOSO versions instead of using the literal example above.
+* ``rhoso_mcps`` — the one flag that does need to be set. Deploys the MCP
+  introspection sidecar, which is read-only **by default**. See
+  :doc:`usage`.
+* ``rhosMCPConfig`` is deep-merged on top of the operator's own defaults
+  — it can override anything the default config sets, including the
+  ``allow_write`` flags that keep introspection read-only. Only set this
+  if you understand exactly what you're overriding.

docs/development.rst

@@ -0,0 +1,68 @@
+Development
+============
+
+This page is for contributors and anyone testing changes locally — not
+needed if you're just installing and using the operator.
+
+.. _dont-have-a-cluster-yet-crc:
+
+Local cluster (CRC)
+-----------------------
+
+For local development/testing only (not for trying the assistant for real
+— CRC is resource-constrained). Deploy a CRC cluster before
+:ref:`installing-the-operator`:
+
+.. code-block:: bash
+
+   git clone https://github.com/openstack-k8s-operators/install_yamls.git
+   cd install_yamls/devsetup
+   make download_tools
+
+   CRC_VERSION=2.51.0 PULL_SECRET=~/work/pull-secret CRC_MONITORING_ENABLED=true CPUS=12 MEMORY=25600 DISK=100 make crc
+   make crc_attach_default_interface
+   eval $(crc oc-env)
+   cd ../..
+
+``PULL_SECRET`` is the same pull secret from :ref:`redhat-registry-access`.
+
+CRC's console is always at a fixed address:
+`console-openshift-console.apps-crc.testing
+<https://console-openshift-console.apps-crc.testing>`_ — not something you
+look up with ``oc whoami --show-console``.
+
+Running CRC remotely? Reach that console with ``sshuttle``:
+
+* Add to your local ``/etc/hosts`` (keep the IP as-is):
+  ``192.168.130.11 api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing``
+* Run ``sshuttle -r $remote_username@$remote_server 192.168.130.0/24``.
+
+Architecture
+---------------
+
+.. mermaid::
+
+   graph TB
+       User[System Administrator] -->|uses console widget| Plugin
+
+       subgraph ns["openstack-lightspeed namespace"]
+           CR[OpenStackLightspeed CR] --> Operator[lightspeed-operator]
+           Operator --> Plugin[Console Plugin]
+           Operator --> DB[(PostgreSQL)]
+           Operator --> OKP[OKP]
+           Operator --> Pod
+
+           subgraph Pod["lightspeed-stack pod"]
+               API[lightspeed-service-api] --> OGX[llama-stack]
+               OGX -.-> MCP[MCP tools sidecar]
+           end
+       end
+
+       Plugin --> API
+       OGX --> OKP
+       OGX --> LLM[Your LLM endpoint]
+       MCP -.->|read-only, optional| OSP[Your OpenStack / OpenShift APIs]
+
+**OKP is deployed on every install, not opt-in.** It's the default RAG
+source; the bundled community documentation is available too, but only if
+you explicitly opt in. See :doc:`configuration` for details.

docs/index.rst

@@ -0,0 +1,38 @@
+OpenStack Lightspeed Operator documentation
+============================================
+
+OpenStack Lightspeed is an AI-powered assistant, tailored for Red Hat
+OpenStack Services on OpenShift (RHOSO), that lives inside the OpenShift
+web console and answers questions in plain English — grounded in real
+documentation, not guesses.
+
+Ask it something like *"How do I create a VM using the OpenStack CLI?"* or
+*"Why would a Nova compute service show as down?"* — see :doc:`usage` for
+more.
+
+You don't need an existing RHOSO deployment to try it — an OpenShift
+cluster and an LLM you can point it at is enough (see :doc:`quickstart`).
+
+.. important::
+
+   This is a community release. Support is provided **upstream only**,
+   via GitHub Issues — there is no separate commercial support channel
+   for this project:
+
+   * `lightspeed-operator issues <https://github.com/openstack-k8s-operators/lightspeed-operator/issues>`_
+   * `lightspeed-rag-content issues <https://github.com/openstack-k8s-operators/lightspeed-rag-content/issues>`_
+   * `lightspeed-mcps issues <https://github.com/openstack-k8s-operators/lightspeed-mcps/issues>`_
+
+   See :doc:`troubleshooting` for what to check, and what to include,
+   before filing an issue.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   quickstart
+   install_guide
+   configuration
+   development
+   troubleshooting
+   usage