docs, api, other stuff update #101
Conversation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughRestructures documentation site (landing page, nav), adds Getting Started and supply-chain/SBOM docs, consolidates reference docs, expands SSE architecture with testing guidance, simplifies SECURITY.md to a single secret-management line, and removes WebSocket settings in favor of SSE-related config. Changes
Sequence Diagram(s)sequenceDiagram
participant Tester as Test Runner
participant ASGIClient as async-asgi-testclient
participant Server as App Server
participant SSE as SSE Stream
Tester->>ASGIClient: start streaming request (with cookies/CSRF)
ASGIClient->>Server: open SSE connection
Server->>SSE: emit events
SSE-->>ASGIClient: stream events chunked
ASGIClient-->>Tester: provide streamed events for assertions
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 9 files
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="mkdocs.yml">
<violation number="1" location="mkdocs.yml:107">
P2: Nav entry points to a missing `getting-started.md`, which will break MkDocs builds. Add the file under docs/ or update the path to an existing document.</violation>
<violation number="2" location="mkdocs.yml:170">
P2: Nav entry points to a missing `security/supply-chain.md`. Add the document under docs/security/ or update the nav to an existing file.</violation>
</file>
<file name="docs/reference/environment-variables.md">
<violation number="1" location="docs/reference/environment-variables.md:53">
P2: The legend defaults contradict the actual values in `backend/.env` that are included in the same doc, which can mislead users who copy the file. Align the legend defaults with the real `.env` values or clarify that the legend is only illustrative.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@docs/components/sse/sse-architecture.md`:
- Around line 88-92: Update the SSE testing guidance to warn that the
recommended dependency async-asgi-testclient appears unmaintained (last updated
June 2022) and may be incompatible with current Python/dependency versions;
mention this maintenance caveat alongside the existing explanation of
httpx.AsyncClient/ASGITransport buffering behavior and SSE streaming
limitations, and add brief alternatives to try (for example, Falcon's
ASGIConductor or testing against a real server with httpx-sse). Reference the
exact symbols in the doc (httpx.AsyncClient, ASGITransport,
async-asgi-testclient, SSE) so readers can locate the affected section and
verify compatibility before adopting the recommendation.
In `@docs/index.md`:
- Around line 22-25: Add a short, explicit "dev-only" warning immediately after
the default credentials line that notes these credentials are for local/dev only
and must be changed before deploying to any non-local environment; update the
sentence that currently reads "log in with `user` / `user123`" to keep the
example but append one concise caution (e.g., "Warning: these default
credentials are for development only — change them before deploying to
production") and optionally link to existing security or configuration docs for
changing credentials.
In `@docs/reference/environment-variables.md`:
- Around line 63-77: The docs section titled "WebSocket & SSE" is misleading and
lists unused `WEBSOCKET_*` settings; update the docs and code to reflect current
SSE usage: rename the section to "SSE (Server-Sent Events)" or "Real-time
Connections", remove or mark `WEBSOCKET_PING_INTERVAL`,
`WEBSOCKET_PING_TIMEOUT`, `WEBSOCKET_MAX_CONNECTIONS_PER_USER`, and
`WEBSOCKET_STALE_CONNECTION_TIMEOUT` as deprecated/legacy both in the docs and
in settings.py, and instead document the actual SSE settings
`SSE_HEARTBEAT_INTERVAL` and `SSE_CONSUMER_POOL_SIZE` (ensure their names match
the symbols in settings.py and the SSE service implementation).
🧹 Nitpick comments (4)
docs/getting-started.md (1)
75-95: Consider using proper headings instead of bold emphasis for troubleshooting items.The troubleshooting section uses bold text (
**text**) for what are effectively subheadings. This triggers MD036 (no-emphasis-as-heading) from markdownlint. Using proper####headings improves accessibility, enables proper navigation/TOC generation, and follows markdown best practices.Suggested fix
## Troubleshooting -**CPU/memory metrics show as `null`** +#### CPU/memory metrics show as `null` The metrics server isn't installed by default in most local Kubernetes setups. Enable it: ```bash kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml-Certificate warnings in browser
+#### Certificate warnings in browserExpected - the stack uses self-signed certs for local development. Accept the warning and continue.
-Services failing to start
+#### Services failing to startCheck logs for the specific service:
docker compose logs backendordocker compose logs kafka. Most issues are either port conflicts (something else using 443, 5001, or 9092) or Docker running out of resources.-Kafka connection errors
+#### Kafka connection errorsKafka takes longer to initialize than most services. Give it a minute after
deploy.sh devfinishes, or watchdocker compose logs kafkauntil you see "started" messages.</details> </blockquote></details> <details> <summary>docs/reference/environment-variables.md (1)</summary><blockquote> `38-40`: **`RATE_LIMITS` appears misplaced in the Kubernetes section.** This variable controls API rate limiting, which is a general backend concern rather than Kubernetes-specific. Consider moving it to the Server section or creating an API section. </blockquote></details> <details> <summary>docs/security/supply-chain.md (1)</summary><blockquote> `27-37`: **Consider noting security implications of `curl | sh` pattern.** While these are official Anchore installation scripts, piping curl directly to shell is a known security concern. Consider adding a brief note about verifying checksums or using package managers where available (e.g., `brew install syft grype` on macOS). </blockquote></details> <details> <summary>docs/index.md (1)</summary><blockquote> `1-12`: **Consider replacing inline styling with a CSS class.** Keeps theming consistent and avoids inline overrides. <details> <summary>♻️ Example refactor</summary> ```diff -<div style="text-align: center;" markdown> +<div class="hero-banner" markdown>Add the class to your theme/extra CSS.
|
Summary by cubic
Revamped docs for easier onboarding and security clarity: new Getting Started guide, streamlined references, and added supply chain security coverage. Also improved SSE testing guidance and updated site navigation.
New Features
Refactors
Written for commit 4fa933b. Summary will update on new commits.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.