docs: restructure user documentation #622

sthaha · 2025-10-09T02:33:59Z

Reorganize user-facing documentation into a better guide structure:

Move API reference to docs/user/reference/api.md
Create new user guide sections: installation, guides, reference
Replace scattered user-guides with organized documentation covering:
- Installation (Kubernetes/OpenShift/monitoring stack setup)
- Usage guides (PowerMonitor, configuration, Grafana, validation)
- Reference (API docs, troubleshooting, uninstallation)
Update README.md with new documentation structure and quick starts
Update tooling paths (.pre-commit-config.yaml, Makefile)
Remove deprecated grafana-deployment.md and assets (moved to user/guides)

This restructure improves documentation discoverability and provides clear installation and usage paths for both Kubernetes and OpenShift users.

codecov · 2025-10-09T02:38:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.26%. Comparing base (88bc67b) to head (8f2ae48).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #622   +/-   ##
=======================================
  Coverage   77.26%   77.26%           
=======================================
  Files          11       11           
  Lines        1267     1267           
=======================================
  Hits          979      979           
  Misses        258      258           
  Partials       30       30

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull Request Overview

This PR restructures the user-facing documentation from scattered docs/user-guides/ files into an organized guide structure with clear installation, usage, and reference sections. The restructuring improves documentation discoverability and provides clear paths for both Kubernetes and OpenShift users.

Key changes:

Creates comprehensive installation guides for Kubernetes and OpenShift platforms
Reorganizes usage guides with detailed PowerMonitor configuration and monitoring setup
Consolidates API documentation and adds complete uninstallation procedures

Reviewed Changes

Copilot reviewed 19 out of 21 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/user/installation/*.md	New installation guides for Kubernetes, OpenShift, and monitoring stack setup
docs/user/guides/*.md	Comprehensive usage guides covering PowerMonitor, configuration, Grafana, validation, upgrading, and troubleshooting
docs/user/reference/*.md	Reference documentation including API specs and uninstallation procedures
docs/user/README.md	New user documentation index with clear navigation and quick starts
hack/dashboard/openshift/README.md	Updated reference path to developer documentation
docs/user/configuring-kepler.md	Updated cross-references to new documentation structure
README.md	Updated with new documentation structure and improved quick start guides
Makefile, .pre-commit-config.yaml	Updated tooling paths for API documentation generation

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

docs/developer/README.md

docs/user/guides/configuration.md

vprashar2929 · 2025-10-09T08:24:32Z

docs/user/guides/configuration.md

+- Override default Kepler settings
+- Provide environment-specific configuration
+
+## Configuration Examples


Isn't this to much info?

docs/user/guides/configuration.md

docs/user/guides/grafana-dashboard.md

vprashar2929 · 2025-10-09T08:32:22Z

docs/user/guides/grafana-dashboard.md

+
+This script automatically:
+
+1. Creates a Grafana instance in the `kepler-operator` namespace


Not really this is wrong

vprashar2929 · 2025-10-09T08:33:29Z

docs/user/guides/grafana-dashboard.md

+3. Imports Kepler dashboards
+4. Sets up necessary RBAC permissions
+
+### Access Grafana on OpenShift


Need updation

vprashar2929 · 2025-10-09T08:34:14Z

docs/user/guides/grafana-dashboard.md

+         ▼
+┌─────────────────┐
+│ ServiceMonitor  │
+│  (kepler)       │


power-monitor ns

docs/user/guides/grafana-dashboard.md

docs/user/guides/power-monitor.md

Signed-off-by: Sunil Thaha <[email protected]>

vprashar2929 · 2025-10-13T04:59:43Z

docs/user/guides/troubleshooting.md

+**Check for common error patterns**:
+
+```bash
+kubectl logs -n kepler-operator deployment/kepler-operator-controller-manager | grep -i error


Suggested change

kubectl logs -n kepler-operator deployment/kepler-operator-controller-manager | grep -i error

kubectl logs -n kepler-operator deployment/kepler-operator-controller | grep -i error

vprashar2929 · 2025-10-13T05:01:01Z

docs/user/guides/troubleshooting.md

+
+```bash
+kubectl get powermonitor -A
+kubectl describe powermonitor <name> -n <namespace>


Do we require specifying namespace?

vprashar2929 · 2025-10-13T05:02:08Z

docs/user/guides/troubleshooting.md

+   kubectl edit powermonitor <name> -n <namespace>
+   ```
+
+1. **Namespace doesn't exist**:


Isn't this handled by operator itself?

vprashar2929 · 2025-10-13T05:03:24Z

docs/user/guides/troubleshooting.md

+   Error: failed to read RAPL: no such file or directory
+   ```
+
+   **Solution**: Enable fake CPU meter via ConfigMap:


This need updation

vprashar2929 · 2025-10-13T05:10:16Z

docs/user/guides/troubleshooting.md

+   Error: failed to access /sys/class/powercap: permission denied
+   ```
+
+   **Solution**: Verify Kepler is running with privileged security context (automatically configured by operator).


Isn't operator responsible for this as well?

vprashar2929 · 2025-10-13T05:11:17Z

docs/user/guides/troubleshooting.md

+
+   ```bash
+   # Operator logs
+   kubectl logs -n kepler-operator deployment/kepler-operator-controller-manager > operator-logs.txt


Suggested change

kubectl logs -n kepler-operator deployment/kepler-operator-controller-manager > operator-logs.txt

kubectl logs -n kepler-operator deployment/kepler-operator-controller > operator-logs.txt

vprashar2929 · 2025-10-13T05:23:29Z

docs/user/installation/openshift.md

+Expected output:
+
+```text
+kepler-operator-controller-manager-xxxxx-yyyyy  2/2   Running  0  1m


Suggested change

kepler-operator-controller-manager-xxxxx-yyyyy 2/2 Running 0 1m

kepler-operator-controller-xxxxx-yyyyy 2/2 Running 0 1m

vprashar2929 · 2025-10-13T05:24:29Z

docs/user/reference/uninstallation.md

+kubectl delete crd keplers.kepler.system.sustainable.computing.io
+kubectl delete crd keplersinternals.kepler.system.sustainable.computing.io


No Kepler and Kepler Internals

vprashar2929 · 2025-10-13T05:27:02Z

docs/user/configuring-kepler.md


   ```bash
+   # For Kubernetes (Helm installation)
+   kubectl logs -n kepler-operator deployment/kepler-operator-controller-manager


Suggested change

kubectl logs -n kepler-operator deployment/kepler-operator-controller-manager

kubectl logs -n kepler-operator deployment/kepler-operator-controller

vprashar2929 · 2025-10-13T05:29:34Z

README.md

-To run the operator locally outside the cluster:
+Get Kepler up and running in minutes. For comprehensive installation instructions, prerequisites, configuration options, and troubleshooting, see the **[Kubernetes Installation Guide](docs/user/installation/kubernetes.md)**.

 ```sh


Isn't this repetition of user guide for installation?

I have refactored the installation docs.

README.md quick and dirty

installation/k8s.md : detailed

monitoring-k8s: setting up prometheus & grafana

vprashar2929 · 2025-10-13T05:30:30Z

README.md

+make cluster-up
+
+# Run operator locally
+make run


Suggested change

make run

make run ENABLE_WEBHOOKS=false

?

Reorganize user-facing documentation into a better guide structure: - Move API reference to docs/user/reference/api.md - Create new user guide sections: installation, guides, reference - Replace scattered user-guides with organized documentation covering: - Installation (Kubernetes/OpenShift/monitoring stack setup) - Usage guides (PowerMonitor, configuration, Grafana, validation) - Reference (API docs, troubleshooting, uninstallation) - Update README.md with new documentation structure and quick starts - Update tooling paths (.pre-commit-config.yaml, Makefile) - Remove deprecated grafana-deployment.md and assets (moved to user/guides) This restructure improves documentation discoverability and provides clear installation and usage paths for both Kubernetes and OpenShift users. Signed-off-by: Sunil Thaha <[email protected]>

github-actions bot added the docs Documentation changes label Oct 9, 2025

sthaha force-pushed the doc-user-guides branch from e32106b to 0371b0c Compare October 9, 2025 04:16

sthaha requested a review from vprashar2929 October 9, 2025 04:16

sthaha marked this pull request as ready for review October 9, 2025 05:36

sthaha force-pushed the doc-user-guides branch 2 times, most recently from 4a27a8b to 907e4a0 Compare October 9, 2025 06:11

sthaha requested a review from Copilot October 9, 2025 06:13

Copilot AI reviewed Oct 9, 2025

View reviewed changes

sthaha force-pushed the doc-user-guides branch 2 times, most recently from 6f76401 to 3b95408 Compare October 9, 2025 07:00