chore: update documentation #566
Conversation
…I configuration, and development
Sumabhat11
added
enhancement
WalkthroughThe pull request restructures the documentation by removing approximately 25 files (primarily CLI commands, contributing guides, migrations, and workflows documentation) and consolidating navigation through VitePress sidebar configuration changes. Key sidebar updates include simplified CLI reference structure, reorganized contributing sections, and expanded default sidebar states. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Areas requiring attention:
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/.vitepress/config.mts (1)
63-127: Fix broken sidebar links for missing migration documentation files.Verification confirms that 3 migration-related documentation files referenced in the sidebar do not exist:
docs/migrations/index.md(line 108)docs/migrations/quick-reference.md(line 109)docs/migrations/templates.md(line 110)All other sidebar paths resolve correctly, including
/cli/cli-reference.mdand/extensions/index.md. Either remove these entries from the sidebar config or ensure the missing migration documentation files are created.
🧹 Nitpick comments (2)
docs/cli/index.md (1)
23-23: Consolidate redundant Reference sections.Lines 23 and 118-120 both reference the same CLI Reference page, creating redundancy. Either remove the reference at line 23 and keep the explicit "Reference" section at the end, or consolidate these into a single, clear reference location to avoid confusion about where users should look for detailed information.
Consider this approach: remove the inline reference at line 23 and strengthen the standalone "Reference" section at the end to be the single source of truth for where to find complete command documentation.
-For detailed command reference, see the [CLI Reference](./cli-reference.md) page.Also applies to: 118-120
docs/contributing/index.md (1)
118-118: Add language identifiers to fenced code blocks.Several code blocks displaying directory structures are missing language identifiers. While not critical, adding them improves rendering consistency.
Based on coding guidelines (markdownlint-cli2 MD040).
Apply these changes:
-``` +```text api/ ├── internal/-``` +```text view/ ├── app/-``` +```text api/internal/features/your-feature/-``` +```text view/app/your-feature/-``` +```text docs/ ├── index.md-``` +```text api/fixtures/development/Also applies to: 132-132, 155-155, 284-284, 374-374, 493-493
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (29)
docs/.vitepress/config.mts(2 hunks)docs/architecture/index.md(0 hunks)docs/cli/commands/clone.md(0 hunks)docs/cli/commands/conf.md(0 hunks)docs/cli/commands/conflict.md(0 hunks)docs/cli/commands/install.md(0 hunks)docs/cli/commands/preflight.md(0 hunks)docs/cli/commands/proxy.md(0 hunks)docs/cli/commands/service.md(0 hunks)docs/cli/commands/test.md(0 hunks)docs/cli/commands/uninstall.md(0 hunks)docs/cli/commands/version.md(0 hunks)docs/cli/config.md(0 hunks)docs/cli/development.md(0 hunks)docs/cli/index.md(2 hunks)docs/contact/index.md(1 hunks)docs/contributing/README.md(0 hunks)docs/contributing/backend.md(0 hunks)docs/contributing/docker.md(0 hunks)docs/contributing/documentation.md(0 hunks)docs/contributing/fixtures.md(0 hunks)docs/contributing/frontend.md(0 hunks)docs/contributing/index.md(1 hunks)docs/contributing/self-hosting.md(0 hunks)docs/install/index.md(1 hunks)docs/migrations/index.md(0 hunks)docs/migrations/quick-reference.md(0 hunks)docs/migrations/templates.md(0 hunks)docs/workflows/index.md(0 hunks)
💤 Files with no reviewable changes (24)
- docs/cli/commands/service.md
- docs/cli/commands/uninstall.md
- docs/contributing/README.md
- docs/cli/commands/preflight.md
- docs/cli/commands/clone.md
- docs/cli/config.md
- docs/contributing/backend.md
- docs/workflows/index.md
- docs/contributing/frontend.md
- docs/cli/development.md
- docs/contributing/docker.md
- docs/architecture/index.md
- docs/cli/commands/proxy.md
- docs/cli/commands/conflict.md
- docs/migrations/index.md
- docs/contributing/fixtures.md
- docs/cli/commands/conf.md
- docs/migrations/quick-reference.md
- docs/cli/commands/test.md
- docs/cli/commands/version.md
- docs/cli/commands/install.md
- docs/migrations/templates.md
- docs/contributing/documentation.md
- docs/contributing/self-hosting.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/contributing/index.md
118-118: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
132-132: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
284-284: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
374-374: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
493-493: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (10)
docs/cli/index.md (2)
27-36: Command table formatting is consistent.The command names are now bold (e.g.,
**preflight**), which improves visual hierarchy in the table. This formatting change aligns well with the goal of simplifying the documentation structure.
23-23: CLI Reference page exists — no action needed.The verification confirms that
docs/cli/cli-reference.mdexists in the repository. The documentation references at lines 23 and 120 are valid.docs/install/index.md (1)
10-16: LGTM! Helpful addition to installation prerequisites.The system requirements section provides clear guidance for users planning their deployment. The specifications are reasonable and well-structured.
docs/contact/index.md (1)
2-2: Verify that the new email address is monitored.The change to a project-specific email address improves professionalism. Please ensure that nixopus@gmail.com is set up and actively monitored for user inquiries.
docs/.vitepress/config.mts (1)
132-154: API Reference badge rendering logic looks sound.The dynamic badge generation for API endpoints is well-implemented. The code correctly:
- Extracts HTTP methods from operation IDs
- Generates styled badges with appropriate classes
- Maps endpoint information to sidebar items
docs/contributing/index.md (5)
1-21: LGTM! Clear introduction and table of contents.The restructured guide provides a comprehensive overview with well-organized sections.
23-112: LGTM! Comprehensive development setup instructions.The expanded setup guide covers all prerequisites and includes detailed steps for:
- Database setup
- SuperTokens configuration
- Dependency installation
- Development fixtures
- Running services locally
This is a significant improvement over the previous documentation.
114-273: Excellent backend development guide with practical examples.The feature creation workflow is well-documented with:
- Clear directory structure
- Code examples for controllers, services, and storage layers
- Route registration instructions
- Migration guidance
This will significantly help new contributors understand the codebase architecture.
274-368: LGTM! Comprehensive frontend development guidance.The frontend section provides:
- Clear page creation workflow
- Redux API service patterns
- Component guidelines
- UI standards
The examples use modern React patterns with TypeScript and follow best practices.
415-604: LGTM! Thorough coverage of testing, Docker, fixtures, and submission workflow.The remaining sections provide:
- Clear testing commands for backend and frontend
- Docker best practices and security guidelines
- Comprehensive fixtures documentation
- Trunk-based development workflow
- Code style guidelines
The guide now serves as an excellent onboarding resource for contributors.
| ## Documentation | ||
|
|
||
| 7. Load development fixtures (optional but recommended): | ||
| ### Documentation Structure | ||
|
|
||
| ```bash | ||
| cd ../api | ||
| ``` | ||
| docs/ | ||
| ├── index.md # Documentation homepage | ||
| ├── architecture/ # System architecture | ||
| ├── install/ # Installation instructions | ||
| ├── features/ # Feature documentation | ||
| └── contributing/ # This file | ||
| ``` | ||
|
|
||
| # Load fixtures without affecting existing data | ||
| make fixtures-load | ||
| ### Adding Documentation | ||
|
|
||
| # Or for a clean slate (drops and recreates tables) | ||
| make fixtures-recreate | ||
| 1. **Create a new markdown file** | ||
| - For a new section: `docs/your-section/index.md` | ||
| - For a new topic: `docs/existing-section/your-topic.md` | ||
|
|
||
| # Get help on fixtures commands | ||
| make fixtures-help | ||
| ``` | ||
| 2. **Add frontmatter** | ||
| ```markdown | ||
| --- | ||
| title: "Your Page Title" | ||
| description: "A brief description" | ||
| --- | ||
| ``` | ||
|
|
||
| The fixtures system provides sample data including users, organizations, roles, permissions, and feature flags to help you get started quickly with development. | ||
| 3. **Follow Documentation Standards** | ||
| - Use clear headers (`#`, `##`, `###`) | ||
| - Include code blocks with syntax highlighting | ||
| - Add tables for structured data | ||
| - Use links for navigation | ||
| - Store images in `/docs/public/` | ||
|
|
||
| ## Running the Application | ||
| 4. **Update Navigation** | ||
| Update `docs/.vitepress/config.mts` to add your page to the sidebar. | ||
|
|
||
| 1. Start the API service: | ||
| ### Running Documentation Locally | ||
|
|
||
| ```bash | ||
| air | ||
| cd docs | ||
| yarn dev | ||
| # Server runs at http://localhost:3001 | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
Verify the architecture directory reference.
Line 377 references docs/architecture/ directory, but according to the PR summary, docs/architecture/index.md was removed. Please verify if this directory still exists or update the documentation structure accordingly.
🏁 Script executed:
#!/bin/bash
# Description: Check if architecture directory exists
if [ -d "docs/architecture" ]; then
echo "✅ docs/architecture/ directory exists"
echo "Contents:"
fd . docs/architecture --type f
else
echo "❌ docs/architecture/ directory not found"
echo "This reference should be removed from the documentation structure"
fiLength of output: 106
Remove the reference to the deleted docs/architecture/ directory from the documentation structure.
The docs/architecture/ directory no longer exists and should be removed from the structure diagram on line 375. Update the documentation structure example to reflect only existing directories.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
374-374: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/contributing/index.md around lines 370 to 413 (specifically line ~375),
the documentation structure diagram still lists the removed docs/architecture/
directory; remove the `├── architecture/ # System architecture` line
from the tree and adjust spacing/branch characters so the remaining entries form
a valid directory tree (e.g., keep index.md, install/, features/,
contributing/), and verify no other references to docs/architecture/ remain in
this section.
There was a problem hiding this comment.
keep the workflows file as it is necessary,
2 participants
Description
This PR updates documentation
Scope of Change
Removed deprecated CLI command references
Minor cleanup of outdated docs files
Updated contact page information
View (UI/UX)
API
CLI
Infra / Deployment
[. ] Docs
Other (specify): ________
Developer Checklist
To be completed by the developer who raised the PR.
Reviewer Checklist
To be completed by the reviewer before merge.
Summary by CodeRabbit
Release Notes
Documentation
Updates