Link out to docs in main docs site #17
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR updates API documentation metadata and descriptions:
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changes
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
|
ℹ️ API content change detected: No structural change, nothing to display.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
http-proxy/overlays/add-external-docs.yaml (2)
11-17: Fix YAML lint: trailing whitespace and missing final newlineThere’s a trailing space after “See also:” (Line 14) and no newline at end of file (Line 17). These will fail yamllint in CI.
Apply this diff:
description: | HTTP Proxy is an HTTP server that exposes operations you can perform directly on a Redpanda cluster. Use the Redpanda HTTP Proxy API to perform a subset of actions that are also available through the Kafka API, but using simpler REST operations. - See also: + See also: - [Use Redpanda Cloud with the HTTP Proxy API](https://docs.redpanda.com/redpanda-cloud/develop/http-proxy/) - [Use Redpanda Self-Managed with the HTTP Proxy API](https://docs.redpanda.com/current/develop/http-proxy/) +
11-17: Optionally add API reference link for symmetry with other specsTo match the pattern used elsewhere (e.g., Control Plane spec), consider adding the API reference link here too.
See also: - [Use Redpanda Cloud with the HTTP Proxy API](https://docs.redpanda.com/redpanda-cloud/develop/http-proxy/) - [Use Redpanda Self-Managed with the HTTP Proxy API](https://docs.redpanda.com/current/develop/http-proxy/) + - [HTTP Proxy API reference](https://docs.redpanda.com/api/doc/http-proxy)schema-registry/overlays/add-external-docs.yaml (2)
11-17: Fix YAML lint: trailing whitespace and missing final newlineThere’s a trailing space after “See also:” (Line 14) and no newline at end of file (Line 17). These violate yamllint rules.
Apply this diff:
description: | Manage schemas within a Redpanda cluster. - See also: + See also: - [Use Redpanda Cloud with the Schema Registry API](https://docs.redpanda.com/redpanda-cloud/manage/schema-reg/schema-reg-api/) - [Use Redpanda Self-Managed with the Schema Registry API](https://docs.redpanda.com/current/manage/schema-reg/schema-reg-api/) +
11-17: Optionally add API reference link for consistencyConsider adding the Schema Registry API reference link as an additional bullet to help users jump directly to the reference.
See also: - [Use Redpanda Cloud with the Schema Registry API](https://docs.redpanda.com/redpanda-cloud/manage/schema-reg/schema-reg-api/) - [Use Redpanda Self-Managed with the Schema Registry API](https://docs.redpanda.com/current/manage/schema-reg/schema-reg-api/) + - [Schema Registry API reference](https://docs.redpanda.com/api/doc/schema-registry)cloud-controlplane/cloud-controlplane.yaml (1)
4887-4887: Optional: Align the delete endpoint description to the Serverless docsThe delete endpoint still references the general Control Plane API docs. For consistency with the create endpoint (and the “Serverless Clusters” tag), consider pointing the delete endpoint to the Serverless-specific page as well.
Proposed description tweak:
- Current (Line 4887): “See Use the Control Plane API…”
- Suggested: “See Use the Control Plane API with Serverless…”
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (3)
cloud-controlplane/cloud-controlplane.yaml(1 hunks)http-proxy/overlays/add-external-docs.yaml(1 hunks)schema-registry/overlays/add-external-docs.yaml(1 hunks)
🧰 Additional context used
🪛 YAMLlint (1.37.1)
http-proxy/overlays/add-external-docs.yaml
[error] 14-14: trailing spaces
(trailing-spaces)
[error] 17-17: no new line character at the end of file
(new-line-at-end-of-file)
schema-registry/overlays/add-external-docs.yaml
[error] 14-14: trailing spaces
(trailing-spaces)
[error] 17-17: no new line character at the end of file
(new-line-at-end-of-file)
🔇 Additional comments (3)
http-proxy/overlays/add-external-docs.yaml (1)
3-11: Overlay structure and target path look correctThe overlay version, actions list, and
$.infotarget withupdate.descriptionare aligned with Bump overlay semantics. No structural concerns.schema-registry/overlays/add-external-docs.yaml (1)
3-11: Overlay structure and target path look correctSingle
updateaction on$.info.descriptionis appropriate, and the literal block content will render Markdown links as intended.cloud-controlplane/cloud-controlplane.yaml (1)
4841-4841: Serverless create description link looks correctThe updated description points to the Serverless Control Plane API docs and aligns with the “Serverless Clusters” tag description below. No functional changes; wording and link LGTM.
If you want to double-check link validity, confirm that this URL resolves and is the intended canonical page:
kbatuigas
deleted the
DOC-1570-Evaluate-whether-remaining-API-content-should-be-moved-to-api-docs
branch
We have content in
docsandcloud-docsthat we are not migrating toapi-docs. These are usage guides that were written to fit within the main Redpanda docs reader journey, and use Antora/AsciiDoc tools such as conditionals, single sourcing, admonitions, etc that aren't supported or don't translate 1:1 within the API reference docs and the Bump platform:cloud-docsto maintain consistency for both APIsThere are cross references embedded in the Cloud API specs (primarily tag, endpoint, and property descriptions), as well as new topics (such as the Data Plane quickstart) that link back out to the relevant RP Cloud docs, but we have not done the same for the other APIs.
This pull request enhances API documentation by updating descriptions and adding external documentation links for the HTTP Proxy and Schema Registry APIs, and by updating a reference in the Serverless Clusters API documentation. These changes improve clarity and provide direct access to relevant guides for users.
Note: We can add more comprehensive descriptions and links out in various places in the different API specs in the future. We should map out the reader journeys inclusive of the new API docs and API Explorer to decide the best way to present the relevant docs to our readers when and where they need them most. This PR just provides a foundation that ensures we have at least some linking across the main docs and all API docs.
API Documentation Improvements:
http-proxy/overlays/add-external-docs.yaml) that provides an enhanced description and includes links to both Redpanda Cloud and Self-Managed HTTP Proxy API documentation.schema-registry/overlays/add-external-docs.yaml) that provides an improved description and links to Redpanda Cloud and Self-Managed Schema Registry API documentation.Reference Update:
cloud-controlplane/cloud-controlplane.yamlto point to the correct Serverless Control Plane API documentation link.