docs: consolidate and streamline documentation structure #21
Conversation
WalkthroughThis PR reorganizes repository documentation: README is simplified and reframed as a docs hub with looser tool/version wording and external links. It removes embedded API/resource content from the README and adds five new docs: Estimated code review effort🎯 2 (Simple) | ⏱️ ~10–15 minutes
Suggested labels
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (7)
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (2)
🧰 Additional context used🧠 Learnings (3)📚 Learning: 2025-12-12T11:04:29.971ZApplied to files:
📚 Learning: 2025-12-12T11:04:29.971ZApplied to files:
📚 Learning: 2025-12-12T11:04:29.971ZApplied to files:
🔇 Additional comments (7)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
README.md(1 hunks)docs/api-resources.md(1 hunks)docs/authentication.md(1 hunks)docs/database.md(1 hunks)docs/deployment.md(1 hunks)docs/development-guide.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Applies to pkg/db/migrations/**/*.go : Store cluster and node pool specifications as JSONB columns to allow flexible cloud provider configurations
Applied to files:
docs/database.md
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Regenerate Go models from openapi/openapi.yaml using make generate command after specification changes
Applied to files:
docs/development-guide.mdREADME.md
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Applies to cmd/hyperfleet/environments/**/*.go : Use environment-based configuration via OCM_ENV to select development, unit_testing, integration_testing, or production settings
Applied to files:
docs/development-guide.md
🪛 markdownlint-cli2 (0.18.1)
docs/deployment.md
64-64: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
139-139: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
144-144: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
149-149: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/database.md
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/development-guide.md
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
114-114: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
125-125: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (5)
docs/authentication.md (1)
1-161: Well-structured authentication documentation with comprehensive examples.The authentication guide clearly covers both development (no-auth) and production (OCM JWT) modes with practical examples, configuration options, and troubleshooting. Cross-references to deployment.md are appropriate.
docs/api-resources.md (1)
410-414: Verify cross-reference to README.md anchor.Line 412 references
[Example Usage](../README.md#example-usage). Confirm that the README.md contains an "## Example Usage" heading (which it does per the updated README.md), so the anchor reference is valid.docs/development-guide.md (1)
46-46: Excellent emphasis on post-clone code generation requirement.The guidance to run
make generate-allafter cloning is clear and well-positioned. This aligns with the code generation workflow and prevents common developer pain points. Based on learnings from previous reviews, this is an important step.README.md (2)
1-168: Successful restructuring from monolithic to modular documentation.The README has been effectively condensed from a comprehensive reference to a clear landing page with appropriate links to detailed documentation. The "Quick Start" section is concise, the "Documentation" section provides good navigation, and the API resource descriptions appropriately defer to docs/api-resources.md. This restructuring achieves the PR objective of consolidating documentation while maintaining accessibility.
50-50: PREREQUISITES.md exists in the repository and the cross-references in README.md are valid. No action needed.Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/authentication.md (2)
64-66: Add language specifier to code block.Line 64 shows a fenced code block without a language specifier. Update to mark it as text:
-``` +```text Authorization: Bearer <jwt-token>--- `139-156`: **Convert emphasis-styled headers to proper markdown headings.** Lines 139, 144, and 149 use bold text (`**...**`) for section headers instead of markdown headings. Convert to level-4 headings (`####`) for correct document structure: ```diff -**401 Unauthorized** +#### 401 Unauthorized - Check token is valid and not expiredApply the same conversion to lines 144 (
**403 Forbidden**) and 149 (**Token debugging**).docs/deployment.md (1)
114-132: Convert step headers to proper markdown headings.Lines 114 and 125 use bold text (
**Step N: ...**) for step headers instead of markdown headings. Convert to level-4 headings (####) for correct document hierarchy:-**Step 1: Create database secret** +#### Step 1: Create database secret ```bash kubectl create secret generic hyperfleet-db-external \Apply the same conversion to line 125 (
**Step 2: Deploy with external database**).docs/api-resources.md (1)
9-15: Add language specifiers to endpoint listing code blocks.Lines 9, 222, and 323 show fenced code blocks without language specifiers. Add
textto properly mark them:-``` +```text GET /api/hyperfleet/v1/clusters POST /api/hyperfleet/v1/clustersApply the same fix to:
- Line 222 (NodePool endpoints)
- Line 323 (Pagination example)
README.md (1)
29-42: Add language specifier to project structure code block.Line 29 shows a project structure diagram in a fenced code block without a language specifier. Add
textorbashto properly mark it:-``` +```text hyperfleet-api/ ├── cmd/hyperfleet-api/ # Application entry point
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
README.md(1 hunks)docs/api-resources.md(1 hunks)docs/authentication.md(1 hunks)docs/database.md(1 hunks)docs/deployment.md(1 hunks)docs/development-guide.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/development-guide.md
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Applies to pkg/db/migrations/**/*.go : Store cluster and node pool specifications as JSONB columns to allow flexible cloud provider configurations
Applied to files:
docs/database.md
🪛 markdownlint-cli2 (0.18.1)
docs/authentication.md
64-64: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
139-139: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
144-144: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
149-149: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
README.md
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/api-resources.md
9-9: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
222-222: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
323-323: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/deployment.md
114-114: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
125-125: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🔇 Additional comments (2)
docs/database.md (1)
1-84: Solid documentation of database architecture and design patterns.The database documentation is well-structured and comprehensive. The schema diagram is clear, and the design patterns section (JSONB for provider-specific configs, soft deletes, migrations) are appropriately detailed. Cross-references to related docs are consistent.
README.md (1)
1-165: Well-executed documentation restructuring with clear external reference hierarchy.The README successfully transitions from an embedded documentation model to a higher-level overview that directs readers to specialized external docs. The Quick Start section is clear and actionable, the documentation links section comprehensively organizes all new docs, and cross-references are consistent. The updates to technology stack (Go 1.24+) and API definition (OpenAPI 3.0) are appropriately generic.
Minor: Address the markdown linting issues flagged above (language specifiers on code blocks, heading syntax), and all five files will provide a cohesive, well-structured documentation experience.
There was a problem hiding this comment.
Actionable comments posted: 7
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
README.md(1 hunks)docs/api-resources.md(1 hunks)docs/authentication.md(1 hunks)docs/database.md(1 hunks)docs/deployment.md(1 hunks)docs/development.md(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Regenerate Go models from openapi/openapi.yaml using make generate command after specification changes
Applied to files:
README.mddocs/development.md
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Applies to cmd/hyperfleet/environments/**/*.go : Use environment-based configuration via OCM_ENV to select development, unit_testing, integration_testing, or production settings
Applied to files:
docs/development.md
📚 Learning: 2025-12-12T11:04:29.971Z
Learnt from: CR
Repo: openshift-hyperfleet/hyperfleet-api PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-12T11:04:29.971Z
Learning: Applies to pkg/db/migrations/**/*.go : Store cluster and node pool specifications as JSONB columns to allow flexible cloud provider configurations
Applied to files:
docs/database.md
🪛 markdownlint-cli2 (0.18.1)
docs/api-resources.md
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/authentication.md
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
docs/development.md (1)
1-379: Well-structured development guide with clear workflows.The file provides comprehensive guidance on setup, development workflow, code generation, mock generation, and troubleshooting. Language specifiers are correctly applied throughout, and references to related documentation are accurate. Based on learnings, the guide appropriately emphasizes the
make generatecommand for OpenAPI code generation and covers tool dependency management via Bingo.README.md (1)
1-165: Well-executed documentation consolidation and restructuring.The README has been appropriately simplified into a documentation hub that points to comprehensive external guides. The Quick Start section is concise and actionable, the Architecture section is clear, and the Documentation section provides good navigation to detailed guides. The shift from embedded technical details to external references follows best practices for documentation organization.
docs/deployment.md
Outdated
|
|
||
| ## Related Documentation | ||
|
|
||
| - [Development Guide](development-guide.md) - Local development setup |
There was a problem hiding this comment.
Fix broken documentation reference.
Line 353 references development-guide.md, but the actual file is docs/development.md:
-[Development Guide](development-guide.md) - Local development setup
+[Development Guide](development.md) - Local development setup📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [Development Guide](development-guide.md) - Local development setup | |
| - [Development Guide](development.md) - Local development setup |
🤖 Prompt for AI Agents
In docs/deployment.md around line 353, the markdown link target points to
development-guide.md which does not exist; update the link to reference the
correct file docs/development.md (or the correct relative path from this file)
so the hyperlink resolves, e.g. change the link target to docs/development.md
and verify the link renders correctly in the built docs.
a language specifier update update
| @@ -0,0 +1,414 @@ | |||
| # API Resources | |||
|
|
|||
| This document provides detailed information about the HyperFleet API resources, including endpoints, request/response formats, and usage patterns. | |||
There was a problem hiding this comment.
I wonder if we need this if we already have the OpenAPI contract and examples.
My concern is to have info duplicated here
I like to have the cURL examples though
| kubectl get svc --namespace hyperfleet-system | ||
| ``` | ||
|
|
||
| ### View Logs |
There was a problem hiding this comment.
For easier use of the examples I prefer if they use ENV variables, so I can copy&paste them right away
e.g.
kubectl logs -f deployment/$NAME --namespace $NAMESPACE
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: rh-amarin The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-merge-bot
bot
merged commit 0520ff0
into
openshift-hyperfleet:main
2 participants
Close HYPERFLEET-352
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.