From 97e78adf07924a20aaa0e2e34efd9253f0a76430 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 22 Jan 2026 14:46:27 +0000 Subject: [PATCH 1/5] feat: Restructure docs navigation to align with Devin.ai This PR restructures the OpenHands documentation navigation to better align with Devin.ai's documentation structure. Key changes include: ## Navigation Changes - **Merge CLI and Web tabs** into a single 'Documentation' tab - **Create new 'Use Cases' tab** with tutorials, examples, and prompt library - **Rename 'SDK' tab to 'API Reference'** and integrate REST API docs - **Add 'Best Practices' section** mirroring Devin's Essential Guidelines ## New Pages Added ### Best Practices (4 pages) - When to Use OpenHands - Writing Effective Instructions - Good vs Bad Instructions - Integrations Overview ### Use Cases Section (15 pages) - Overview and Best Practices - Examples: Code Migrations, Test Coverage, Bug Fixing, Documentation, Refactoring, API Integration - Tutorials: Getting Started, REST API, Test Coverage, Containerization, Frontend Development - Prompt Library: Testing & Refactoring, Data Analysis, Web Development ## Structure Comparison | New Tab | Content | |---------|---------| | Getting Started | Intro, Quick Start, First Projects, FAQs, Community | | Documentation | Merged CLI+Web: Setup, Running, Integrations, Features, Settings | | Use Cases | Examples, Tutorials, Prompt Library (NEW) | | API Reference | SDK, Guides, Architecture, Python & REST APIs | Co-authored-by: openhands --- docs.json | 287 +++++++-------- openhands/usage/integrations/overview.mdx | 76 ++++ .../usage/tips/effective-instructions.mdx | 230 ++++++++++++ .../usage/tips/good-vs-bad-instructions.mdx | 326 ++++++++++++++++++ .../usage/tips/when-to-use-openhands.mdx | 149 ++++++++ use-cases/best-practices.mdx | 296 ++++++++++++++++ use-cases/examples/api-integration.mdx | 108 ++++++ use-cases/examples/bug-fixing.mdx | 135 ++++++++ use-cases/examples/code-migrations.mdx | 158 +++++++++ use-cases/examples/documentation.mdx | 157 +++++++++ use-cases/examples/refactoring.mdx | 124 +++++++ use-cases/examples/test-coverage.mdx | 211 ++++++++++++ use-cases/overview.mdx | 109 ++++++ use-cases/prompts/data-analysis.mdx | 256 ++++++++++++++ use-cases/prompts/testing-refactoring.mdx | 213 ++++++++++++ use-cases/prompts/web-development.mdx | 278 +++++++++++++++ use-cases/tutorials/containerization.mdx | 224 ++++++++++++ use-cases/tutorials/frontend-development.mdx | 198 +++++++++++ use-cases/tutorials/getting-started.mdx | 133 +++++++ use-cases/tutorials/rest-api.mdx | 173 ++++++++++ use-cases/tutorials/test-coverage.mdx | 205 +++++++++++ 21 files changed, 3910 insertions(+), 136 deletions(-) create mode 100644 openhands/usage/integrations/overview.mdx create mode 100644 openhands/usage/tips/effective-instructions.mdx create mode 100644 openhands/usage/tips/good-vs-bad-instructions.mdx create mode 100644 openhands/usage/tips/when-to-use-openhands.mdx create mode 100644 use-cases/best-practices.mdx create mode 100644 use-cases/examples/api-integration.mdx create mode 100644 use-cases/examples/bug-fixing.mdx create mode 100644 use-cases/examples/code-migrations.mdx create mode 100644 use-cases/examples/documentation.mdx create mode 100644 use-cases/examples/refactoring.mdx create mode 100644 use-cases/examples/test-coverage.mdx create mode 100644 use-cases/overview.mdx create mode 100644 use-cases/prompts/data-analysis.mdx create mode 100644 use-cases/prompts/testing-refactoring.mdx create mode 100644 use-cases/prompts/web-development.mdx create mode 100644 use-cases/tutorials/containerization.mdx create mode 100644 use-cases/tutorials/frontend-development.mdx create mode 100644 use-cases/tutorials/getting-started.mdx create mode 100644 use-cases/tutorials/rest-api.mdx create mode 100644 use-cases/tutorials/test-coverage.mdx diff --git a/docs.json b/docs.json index 3738b767..4c747a1e 100644 --- a/docs.json +++ b/docs.json @@ -20,108 +20,103 @@ "navigation": { "tabs": [ { - "tab": "Overview", + "tab": "Getting Started", "pages": [ { - "group": "Overview", + "group": "Getting Started", "pages": [ "overview/introduction", "overview/quickstart", "overview/first-projects", - "overview/faqs", - "overview/community", - "overview/contributing" - ] - }, - { - "group": "Common Features", - "pages": [ - "overview/model-context-protocol", - { - "group": "Skills", - "pages": [ - "overview/skills", - "overview/skills/repo", - "overview/skills/keyword", - "overview/skills/org", - "overview/skills/public" - ] - } + "overview/faqs" ] }, { - "group": "Tips and Tricks", + "group": "Community", "pages": [ - "openhands/usage/tips/prompting-best-practices" - ] - }, - { - "group": "Help", - "pages": [ - "openhands/usage/troubleshooting/troubleshooting", - "openhands/usage/troubleshooting/feedback" + "overview/community", + "overview/contributing" ] } ] }, { - "tab": "Web", + "tab": "Documentation", "pages": [ { - "group": "Key Features", + "group": "Setup & Installation", "pages": [ - "openhands/usage/key-features" + "openhands/usage/cloud/openhands-cloud", + "openhands/usage/cli/installation", + "openhands/usage/run-openhands/local-setup", + "openhands/usage/advanced/configuration-options" ] }, { - "group": "OpenHands Cloud", + "group": "Running OpenHands", "pages": [ - "openhands/usage/cloud/openhands-cloud", + "openhands/usage/cli/terminal", + "openhands/usage/cli/web-interface", + "openhands/usage/cli/headless", + "openhands/usage/cli/gui-server", { - "group": "Integrations", + "group": "IDE Integration (ACP)", "pages": [ - "openhands/usage/cloud/bitbucket-installation", - "openhands/usage/cloud/github-installation", - "openhands/usage/cloud/gitlab-installation", - "openhands/usage/cloud/slack-installation", - { - "group": "Project Management Tools", - "pages": [ - "openhands/usage/cloud/project-management/jira-integration" - ] - } + "openhands/usage/cli/ide/overview", + "openhands/usage/cli/ide/vscode", + "openhands/usage/cli/ide/jetbrains", + "openhands/usage/cli/ide/zed", + "openhands/usage/cli/ide/toad" ] - }, - "openhands/usage/cloud/cloud-ui", - "openhands/usage/cloud/cloud-api" + } ] }, { - "group": "Local GUI", + "group": "Integrations", "pages": [ - "openhands/usage/run-openhands/local-setup", - "openhands/usage/run-openhands/gui-mode" + "openhands/usage/integrations/overview", + "openhands/usage/cloud/github-installation", + "openhands/usage/cloud/gitlab-installation", + "openhands/usage/cloud/bitbucket-installation", + "openhands/usage/cloud/slack-installation", + { + "group": "Project Management", + "pages": [ + "openhands/usage/cloud/project-management/jira-integration", + "openhands/usage/cloud/project-management/linear-integration" + ] + }, + "openhands/usage/cli/mcp-servers" ] }, { - "group": "REST API", - "openapi": "openapi/openapi.json" - }, - { - "group": "Customizations & Settings", + "group": "Features & Configuration", "pages": [ + "openhands/usage/key-features", { - "group": "OpenHands Settings", + "group": "Skills", "pages": [ - "openhands/usage/settings/application-settings", - "openhands/usage/settings/llm-settings", - "openhands/usage/settings/integrations-settings", - "openhands/usage/settings/secrets-settings", - "openhands/usage/settings/api-keys-settings", - "openhands/usage/settings/mcp-settings" + "overview/skills", + "overview/skills/repo", + "overview/skills/keyword", + "overview/skills/org", + "overview/skills/public" ] }, - "openhands/usage/customization/repository" + "overview/model-context-protocol", + "openhands/usage/customization/repository", + "openhands/usage/cli/critic" + ] + }, + { + "group": "Settings", + "pages": [ + "openhands/usage/settings/application-settings", + "openhands/usage/settings/llm-settings", + "openhands/usage/settings/integrations-settings", + "openhands/usage/settings/secrets-settings", + "openhands/usage/settings/api-keys-settings", + "openhands/usage/settings/mcp-settings" ] }, { @@ -170,66 +165,86 @@ } ] }, - "openhands/usage/advanced/configuration-options", "openhands/usage/advanced/custom-sandbox-guide", "openhands/usage/advanced/search-engine-setup" ] + }, + { + "group": "Best Practices", + "pages": [ + "openhands/usage/tips/prompting-best-practices", + "openhands/usage/tips/when-to-use-openhands", + "openhands/usage/tips/effective-instructions", + "openhands/usage/tips/good-vs-bad-instructions" + ] + }, + { + "group": "Cloud Features", + "pages": [ + "openhands/usage/cloud/cloud-ui", + "openhands/usage/cloud/cloud-api", + "openhands/usage/cli/cloud" + ] + }, + { + "group": "Reference", + "pages": [ + "openhands/usage/cli/command-reference", + "openhands/usage/cli/resume" + ] + }, + { + "group": "Help", + "pages": [ + "openhands/usage/troubleshooting/troubleshooting", + "openhands/usage/troubleshooting/feedback" + ] } ] }, { - "tab": "CLI", + "tab": "Use Cases", "pages": [ { - "group": "Getting Started", - "pages": [ - "openhands/usage/cli/installation", - "openhands/usage/cli/quick-start" - ] - }, - { - "group": "Ways to Run", + "group": "Overview", "pages": [ - "openhands/usage/cli/terminal", - "openhands/usage/cli/headless", - "openhands/usage/cli/web-interface", - "openhands/usage/cli/gui-server", - { - "group": "IDE Integration (ACP)", - "pages": [ - "openhands/usage/cli/ide/overview", - "openhands/usage/cli/ide/zed", - "openhands/usage/cli/ide/toad", - "openhands/usage/cli/ide/vscode", - "openhands/usage/cli/ide/jetbrains" - ] - } + "use-cases/overview", + "use-cases/best-practices" ] }, { - "group": "Cloud", + "group": "Use Cases", "pages": [ - "openhands/usage/cli/cloud" + "use-cases/examples/code-migrations", + "use-cases/examples/test-coverage", + "use-cases/examples/bug-fixing", + "use-cases/examples/documentation", + "use-cases/examples/refactoring", + "use-cases/examples/api-integration" ] }, { - "group": "Extensions", + "group": "Tutorials", "pages": [ - "openhands/usage/cli/mcp-servers", - "openhands/usage/cli/critic" + "use-cases/tutorials/getting-started", + "use-cases/tutorials/rest-api", + "use-cases/tutorials/test-coverage", + "use-cases/tutorials/containerization", + "use-cases/tutorials/frontend-development" ] }, { - "group": "Reference", + "group": "Prompt Library", "pages": [ - "openhands/usage/cli/command-reference", - "openhands/usage/cli/resume" + "use-cases/prompts/testing-refactoring", + "use-cases/prompts/data-analysis", + "use-cases/prompts/web-development" ] } ] }, { - "tab": "SDK", + "tab": "API Reference", "pages": [ "sdk/index", "sdk/getting-started", @@ -250,41 +265,41 @@ "sdk/guides/metrics", "sdk/guides/observability", "sdk/guides/secrets", + "sdk/guides/hooks", + "sdk/guides/critic", { - "group": "LLM Features", + "group": "Agent Configurations", "pages": [ - "sdk/guides/llm-registry", - "sdk/guides/llm-routing", - "sdk/guides/llm-reasoning", - "sdk/guides/llm-streaming", - "sdk/guides/llm-image-input", - "sdk/guides/llm-error-handling" - ] - }, - { - "group": "Agent Features", - "pages": [ - "sdk/guides/agent-interactive-terminal", - "sdk/guides/agent-browser-use", "sdk/guides/agent-custom", - "sdk/guides/convo-custom-visualizer", - "sdk/guides/agent-stuck-detector", + "sdk/guides/agent-browser-use", "sdk/guides/agent-tom-agent", - "sdk/guides/critic" + "sdk/guides/agent-interactive-terminal", + "sdk/guides/agent-stuck-detector" ] }, { - "group": "Conversation Features", + "group": "Conversation Management", "pages": [ + "sdk/guides/convo-async", "sdk/guides/convo-pause-and-resume", "sdk/guides/convo-send-message-while-running", - "sdk/guides/convo-async", "sdk/guides/convo-ask-agent", - "sdk/guides/hooks" + "sdk/guides/convo-custom-visualizer" + ] + }, + { + "group": "LLM Configuration", + "pages": [ + "sdk/guides/llm-registry", + "sdk/guides/llm-routing", + "sdk/guides/llm-streaming", + "sdk/guides/llm-reasoning", + "sdk/guides/llm-image-input", + "sdk/guides/llm-error-handling" ] }, { - "group": "Remote Agent Server", + "group": "Agent Server", "pages": [ "sdk/guides/agent-server/overview", "sdk/guides/agent-server/local-server", @@ -292,22 +307,15 @@ "sdk/guides/agent-server/apptainer-sandbox", "sdk/guides/agent-server/api-sandbox", "sdk/guides/agent-server/cloud-workspace", - "sdk/guides/agent-server/custom-tools", - { - "group": "API Reference", - "openapi": { - "source": "/openapi/agent-sdk.json", - "directory": "sdk/guides/agent-server/api-reference" - } - } + "sdk/guides/agent-server/custom-tools" ] }, { "group": "GitHub Workflows", "pages": [ - "sdk/guides/github-workflows/assign-reviews", "sdk/guides/github-workflows/pr-review", - "sdk/guides/github-workflows/todo-management" + "sdk/guides/github-workflows/todo-management", + "sdk/guides/github-workflows/assign-reviews" ] } ] @@ -317,15 +325,18 @@ "pages": [ "sdk/arch/overview", "sdk/arch/design", + "sdk/arch/sdk", { - "group": "SDK Components", + "group": "Components", "pages": [ "sdk/arch/agent", + "sdk/arch/agent-server", "sdk/arch/conversation", "sdk/arch/tool-system", "sdk/arch/events", "sdk/arch/workspace", "sdk/arch/llm", + "sdk/arch/mcp", "sdk/arch/skill", "sdk/arch/condenser", "sdk/arch/security" @@ -334,7 +345,7 @@ ] }, { - "group": "API Reference", + "group": "Python API Reference", "pages": [ "sdk/api-reference/openhands.sdk.agent", "sdk/api-reference/openhands.sdk.conversation", @@ -345,6 +356,10 @@ "sdk/api-reference/openhands.sdk.utils", "sdk/api-reference/openhands.sdk.workspace" ] + }, + { + "group": "REST API", + "openapi": "openapi/openapi.json" } ] } @@ -459,10 +474,6 @@ "source": "/openhands/usage/prompting/microagents-public", "destination": "/openhands/usage/microagents/microagents-public" }, - { - "source": "/openhands/usage/prompting/microagents-repo", - "destination": "/openhands/usage/microagents/microagents-repo" - }, { "source": "/openhands/usage/installation", "destination": "/openhands/usage/quick-start" @@ -578,6 +589,10 @@ { "source": "/openhands/usage/run-openhands/cli/resume", "destination": "/openhands/usage/cli/resume" + }, + { + "source": "/sdk", + "destination": "/sdk/index" } ] -} \ No newline at end of file +} diff --git a/openhands/usage/integrations/overview.mdx b/openhands/usage/integrations/overview.mdx new file mode 100644 index 00000000..ec17e45d --- /dev/null +++ b/openhands/usage/integrations/overview.mdx @@ -0,0 +1,76 @@ +--- +title: "Integrations Overview" +sidebarTitle: "Overview" +description: "Connect OpenHands to your existing tools and workflows" +--- + +# Integrations Overview + +OpenHands integrates with your existing development tools to fit seamlessly into your workflow. + +## Source Control + +Connect OpenHands to your repositories for seamless code management. + + + + Connect to GitHub repositories + + + Connect to GitLab repositories + + + Connect to Bitbucket repositories + + + +## Communication + +Stay connected with your team through integrated messaging platforms. + + + + Interact with OpenHands from Slack + + + +## Project Management + +Track tasks and issues with your preferred project management tools. + + + + Connect to Jira for issue tracking + + + Connect to Linear for project management + + + +## Extensions + +Extend OpenHands functionality with additional tools. + + + + Add Model Context Protocol servers + + + +## Platform Availability + + +Source control and project management integrations are available in **OpenHands Cloud**. +MCP server configuration is available in both the **CLI** and **Cloud** versions. + + +## Getting Started + +1. **Choose your platform**: Decide whether to use [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) or [self-hosted](/openhands/usage/run-openhands/local-setup) deployment +2. **Connect source control**: Link your GitHub, GitLab, or Bitbucket account +3. **Add communication**: Enable Slack integration for team collaboration +4. **Configure project management**: Connect Jira or Linear for issue tracking + +## API Integration + +For programmatic access, see our [Cloud API](/openhands/usage/cloud/cloud-api) documentation or the [REST API Reference](/api-reference). diff --git a/openhands/usage/tips/effective-instructions.mdx b/openhands/usage/tips/effective-instructions.mdx new file mode 100644 index 00000000..4dbec5e6 --- /dev/null +++ b/openhands/usage/tips/effective-instructions.mdx @@ -0,0 +1,230 @@ +--- +title: "Writing Effective Instructions" +sidebarTitle: "Effective Instructions" +description: "How to write clear, effective instructions for OpenHands" +--- + +# Writing Effective Instructions + +The quality of OpenHands' output depends significantly on how you communicate your task. This guide covers techniques for writing clear, effective instructions. + +## The Anatomy of a Good Instruction + +A well-structured instruction includes: + + + + Background information OpenHands needs to understand the task + + + What you want to accomplish + + + Boundaries and limitations to work within + + + How to confirm the task is complete + + + +## Writing Clear Instructions + +### Be Specific, Not Vague + + + + ``` + Fix the API + ``` + + + ``` + Fix the /api/users endpoint that returns a 500 error + when the email field is missing from the request body. + + Expected behavior: Return a 400 error with message + "Email is required" when email is not provided. + ``` + + + +### Provide Necessary Context + +Include information that isn't obvious from the code: + +```markdown +Context: +- We use PostgreSQL for the database +- The User model is in src/models/user.py +- We follow the repository pattern for data access +- Related tests are in tests/test_user.py + +Task: +Add a "last_login" timestamp field to the User model that +updates automatically when a user authenticates. +``` + +### Define Acceptance Criteria + +Clearly state what "done" looks like: + +```markdown +Acceptance Criteria: +1. The login endpoint updates last_login on successful authentication +2. last_login is included in the user profile response +3. All existing tests continue to pass +4. New tests cover the last_login functionality +``` + +## Instruction Templates + +### Bug Fix Template + +```markdown +## Bug Description +[Describe the bug and its symptoms] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [Expected vs actual result] + +## Root Cause (if known) +[Any insights into what's causing the bug] + +## Acceptance Criteria +- [ ] Bug no longer reproduces +- [ ] Existing tests pass +- [ ] New test added to prevent regression +``` + +### Feature Implementation Template + +```markdown +## Feature Description +[What the feature should do] + +## Requirements +- [Requirement 1] +- [Requirement 2] + +## Technical Constraints +- [Technologies to use] +- [Patterns to follow] +- [Files/areas to modify] + +## Acceptance Criteria +- [ ] [Criterion 1] +- [ ] [Criterion 2] +- [ ] Tests added +- [ ] Documentation updated +``` + +### Refactoring Template + +```markdown +## Current State +[Describe the current implementation] + +## Desired State +[Describe the target implementation] + +## Scope +- Files to modify: [list files] +- Files NOT to modify: [list files] + +## Constraints +- Maintain backward compatibility +- No changes to public APIs +- All tests must pass + +## Verification +[How to verify the refactoring is successful] +``` + +## Advanced Techniques + +### Break Down Complex Tasks + +Instead of one large instruction, use multiple smaller ones: + +```markdown +Phase 1: Set up the database schema +- Add migration for new tables +- Update models + +Phase 2: Implement the service layer +- Create UserService class +- Add CRUD methods + +Phase 3: Add API endpoints +- Create routes +- Add request validation +- Write tests +``` + +### Provide Examples + +When patterns matter, show examples: + +```markdown +Follow the existing pattern for API handlers. For example, +see how we handle the /api/products endpoint: + +```python +@app.route('/api/products', methods=['GET']) +def get_products(): + products = ProductService.get_all() + return jsonify([p.to_dict() for p in products]) +``` + +Implement a similar endpoint for /api/orders. +``` + +### Reference Documentation + +Point to relevant resources: + +```markdown +Implement OAuth2 authentication following the specification at: +https://oauth.net/2/ + +Use our existing HTTP client wrapper in src/utils/http.py +for making external requests. +``` + +## Common Pitfalls to Avoid + + + + Don't assume OpenHands knows about conventions, tools, or patterns specific to your project. Be explicit. + + + Don't combine too many unrelated tasks in one instruction. Keep tasks focused. + + + Avoid words like "improve," "better," or "clean up" without specific criteria. + + + Always include how to verify the work is correct. + + + +## Using Skills for Repeated Instructions + +If you find yourself writing similar instructions repeatedly, consider creating a [Skill](/overview/skills) to encode common patterns and context. + + + Create reusable context and instructions for your repositories + + +## Next Steps + + + + See examples of effective and ineffective instructions + + + More tips for getting the best results + + diff --git a/openhands/usage/tips/good-vs-bad-instructions.mdx b/openhands/usage/tips/good-vs-bad-instructions.mdx new file mode 100644 index 00000000..cb96cda0 --- /dev/null +++ b/openhands/usage/tips/good-vs-bad-instructions.mdx @@ -0,0 +1,326 @@ +--- +title: "Good vs Bad Instructions" +sidebarTitle: "Good vs Bad Instructions" +description: "Examples of effective and ineffective instructions for OpenHands" +--- + +# Good vs Bad Instructions + +Learn from real examples what makes instructions effective—and what causes them to fail. + +## Bug Fixing Examples + +### Example 1: Login Error + + + + ``` + The login is broken, fix it + ``` + + **Why it fails:** + - No description of the actual problem + - No reproduction steps + - No indication of where to look + - No way to verify the fix + + + ``` + Fix the login authentication error. + + Problem: Users receive "Invalid credentials" even with correct + username/password. The issue started after commit abc123. + + To reproduce: + 1. Go to /login + 2. Enter: test@example.com / password123 + 3. Click "Sign In" + 4. Error appears even though credentials are valid in the database + + Suspected cause: The password hashing was changed but the + comparison logic wasn't updated. + + Files to check: + - src/auth/login.py + - src/utils/password.py + + Verify fix by: + 1. Running: pytest tests/test_auth.py + 2. Manually testing login with test credentials + ``` + + + +### Example 2: API Response Error + + + + ``` + The API returns wrong data sometimes + ``` + + + ``` + Fix inconsistent API response format for /api/users/{id} + + Current behavior: + - Sometimes returns: {"user": {"id": 1, "name": "John"}} + - Sometimes returns: {"id": 1, "name": "John"} + + Expected behavior: + - Always return: {"user": {"id": 1, "name": "John"}} + + The inconsistency happens because some code paths use + user.to_dict() directly while others wrap it in {"user": ...} + + Fix by ensuring all return paths in src/api/users.py use + the UserResponse schema from src/schemas/user.py + ``` + + + +## Feature Implementation Examples + +### Example 3: Adding a Feature + + + + ``` + Add email notifications + ``` + + **Why it fails:** + - No specification of what triggers notifications + - No template requirements + - No indication of email service to use + - No scope boundaries + + + ``` + Add email notification when a user's order ships. + + Requirements: + 1. Send email when order status changes to "shipped" + 2. Use the existing EmailService in src/services/email.py + 3. Email should include: + - Order number + - Tracking number + - Estimated delivery date + - List of items + + Template location: Create new template at + templates/emails/order_shipped.html + + Trigger: Add to the update_order_status() method in + src/services/order.py + + Configuration: Use existing SMTP settings from config.py + + Tests: Add tests in tests/test_order_notifications.py + + Do NOT modify: + - The Order model + - Existing email templates + - The email service itself + ``` + + + +### Example 4: UI Component + + + + ``` + Make a nice dashboard + ``` + + + ``` + Create a sales dashboard component showing monthly metrics. + + Component: src/components/SalesDashboard.tsx + + Required sections: + 1. Summary cards showing: + - Total revenue (from /api/metrics/revenue) + - Order count (from /api/metrics/orders) + - Average order value (calculated) + + 2. Line chart showing daily sales for the current month + - Use the existing Chart component from src/components/Chart + - Data from /api/metrics/daily-sales + + Styling: + - Follow existing Tailwind patterns in other dashboard components + - Use the Card component from src/components/ui/Card + - Responsive: stack on mobile, grid on desktop + + Loading states: + - Show skeleton loaders while data fetches + - Show error state if API calls fail + + Tests: Add component tests in __tests__/SalesDashboard.test.tsx + ``` + + + +## Refactoring Examples + +### Example 5: Code Cleanup + + + + ``` + Clean up the utils folder + ``` + + + ``` + Refactor src/utils/ to remove duplicate helper functions. + + Analysis needed: + 1. Find duplicate or near-duplicate functions across: + - src/utils/string.py + - src/utils/format.py + - src/utils/helpers.py + + Actions: + 1. Consolidate string formatting functions into src/utils/string.py + 2. Remove duplicates, keeping the most complete implementation + 3. Update all imports in the codebase + 4. Add type hints to all consolidated functions + 5. Add docstrings following Google style + + Constraints: + - Maintain backward compatibility (keep function signatures) + - All existing tests must pass + - Do not rename any public functions + + Verify: + - Run: pytest tests/ + - Run: mypy src/utils/ + ``` + + + +### Example 6: Architecture Change + + + + ``` + We need to use TypeScript now + ``` + + + ``` + Migrate src/components/Button.jsx to TypeScript. + + Steps: + 1. Rename Button.jsx to Button.tsx + 2. Add TypeScript types for all props: + - variant: 'primary' | 'secondary' | 'danger' + - size: 'sm' | 'md' | 'lg' + - disabled: boolean + - onClick: (event: MouseEvent) => void + - children: ReactNode + + 3. Export the Props type as ButtonProps + 4. Update imports in files that use Button + 5. Run type checking: npx tsc --noEmit + + Follow the pattern established in src/components/Input.tsx + for type definitions. + + Do NOT migrate other components in this task. + ``` + + + +## Test Writing Examples + +### Example 7: Adding Tests + + + + ``` + Add tests for the user module + ``` + + + ``` + Add unit tests for UserService.create_user() method. + + Location: tests/services/test_user_service.py + + Test cases to cover: + 1. Successful user creation with valid data + 2. Failure when email already exists (expect DuplicateEmailError) + 3. Failure when password is too short (expect ValidationError) + 4. Failure when required fields are missing + 5. Verify password is hashed before storing + + Test setup: + - Use pytest fixtures from conftest.py + - Mock the database with the existing mock_db fixture + - Use factory_boy for test data (see tests/factories.py) + + Assertions should verify: + - Return value matches expected user object + - Database method was called with correct arguments + - Appropriate exceptions are raised with correct messages + ``` + + + +## Common Patterns + +### The Context-Task-Verify Pattern + +Structure your instructions with these three sections: + +```markdown +## Context +[Background information, relevant files, existing patterns] + +## Task +[Specific changes to make, with clear scope] + +## Verify +[How to confirm the task is complete and correct] +``` + +### The Problem-Solution-Constraints Pattern + +For bug fixes: + +```markdown +## Problem +[What's wrong, how to reproduce] + +## Solution +[Expected fix approach or outcome] + +## Constraints +[What should NOT change, compatibility requirements] +``` + +## Quick Reference + +| Aspect | ❌ Avoid | ✅ Do | +|--------|---------|-------| +| Scope | "Fix everything" | "Fix X in file Y" | +| Details | "Make it better" | "Change A to B because C" | +| Verification | (none) | "Run tests, check output" | +| Context | Assumptions | Explicit file paths, patterns | +| Boundaries | Open-ended | "Only modify these files" | + +## Next Steps + + + + More tips for effective prompting + + + Learn which tasks work best with OpenHands + + diff --git a/openhands/usage/tips/when-to-use-openhands.mdx b/openhands/usage/tips/when-to-use-openhands.mdx new file mode 100644 index 00000000..c0dbfbfd --- /dev/null +++ b/openhands/usage/tips/when-to-use-openhands.mdx @@ -0,0 +1,149 @@ +--- +title: "When to Use OpenHands" +sidebarTitle: "When to Use OpenHands" +description: "Learn when OpenHands is most effective and how to get the best results" +--- + +# When to Use OpenHands + +OpenHands excels at certain types of tasks. Understanding when to use it—and when not to—will help you get the best results. + +## Ideal Use Cases + +### 1. Well-Defined, Scoped Tasks + +OpenHands performs best on tasks with clear boundaries and acceptance criteria: + +- **Bug fixes** with specific reproduction steps +- **Feature additions** with clear requirements +- **Refactoring** with well-defined scope +- **Test writing** for existing functionality +- **Documentation updates** with specific content needs + +### 2. Repetitive Engineering Tasks + +Tasks you've done many times before: + +- Adding unit tests to existing code +- Implementing CRUD endpoints +- Setting up boilerplate for new features +- Migrating code patterns across files +- Updating dependencies and fixing breaking changes + +### 3. Code Exploration and Understanding + +When you need to understand a codebase: + +- Answering questions about how code works +- Finding where functionality is implemented +- Explaining complex code patterns +- Identifying dependencies between components + +### 4. Parallel Task Execution + +Running multiple independent tasks simultaneously: + +- Fixing multiple independent bugs +- Adding tests across different modules +- Updating documentation in parallel +- Migrating multiple files with similar changes + +## Less Ideal Use Cases + +### Tasks Requiring External Context + +OpenHands works best when context is available in the codebase: + + +**Challenging scenarios:** +- Tasks requiring proprietary business knowledge not in code +- Decisions needing stakeholder input +- Work depending on external systems without documentation + + +### Large-Scale Architectural Changes + +For major restructuring, consider breaking work into phases: + +- **Instead of**: "Rewrite the entire authentication system" +- **Try**: "Add JWT support to the existing auth module" → "Migrate user sessions to JWT" → "Remove legacy auth code" + +### Highly Creative or Subjective Work + +Tasks with subjective quality criteria may need more guidance: + +- UI/UX design decisions +- Naming conventions without established patterns +- Architecture decisions without clear requirements + +## Best Practices Checklist + +Before starting a task, verify: + + + + Can you describe what "done" looks like? + + + Can you verify the result programmatically or visually? + + + Is the necessary information in the codebase or can you provide it? + + + Is the task small enough to complete in one session? + + + +## Task Complexity Guidelines + +| Complexity | Example | Recommendation | +|------------|---------|----------------| +| **Simple** | Fix a typo, add a test | Single prompt, minimal guidance | +| **Medium** | Implement a feature, fix a bug | Provide context and acceptance criteria | +| **Complex** | Multi-file refactoring | Break into subtasks, provide detailed guidance | +| **Very Complex** | Architectural changes | Consider human-led design with OpenHands implementation | + +## Maximizing Success + +### 1. Provide Clear Instructions + +Be specific about what you want: + +``` +❌ "Fix the login bug" +✅ "Fix the login bug where users see a blank page after clicking submit. + The error appears in the console as 'undefined is not a function'. + The bug was introduced in PR #123." +``` + +### 2. Include Verification Steps + +Tell OpenHands how to verify its work: + +``` +✅ "After implementing, run `npm test` to ensure all tests pass, + and manually test by logging in with test credentials." +``` + +### 3. Set Boundaries + +Define what should and shouldn't change: + +``` +✅ "Modify only files in the `src/auth/` directory. + Do not change the public API signatures." +``` + +## Getting Help + +If you're unsure whether a task is suitable for OpenHands: + +1. Start with a smaller version of the task +2. Provide more context than you think necessary +3. Use [iterative refinement](/sdk/guides/iterative-refinement) to improve results +4. Check the [prompting best practices](/openhands/usage/tips/prompting-best-practices) guide + + + Share your use case with the community for guidance + diff --git a/use-cases/best-practices.mdx b/use-cases/best-practices.mdx new file mode 100644 index 00000000..aca1c543 --- /dev/null +++ b/use-cases/best-practices.mdx @@ -0,0 +1,296 @@ +--- +title: "Use Case Best Practices" +sidebarTitle: "Best Practices" +description: "Maximize success with OpenHands across different use cases" +--- + +# Use Case Best Practices + +Learn how to get the best results from OpenHands for different types of tasks. + +## General Principles + + + + Complex projects should be divided into smaller, independent tasks that can be completed and verified individually. + + **Instead of:** "Rewrite the authentication system" + + **Try:** + 1. "Add password strength validation" + 2. "Implement JWT token refresh" + 3. "Add rate limiting to login endpoint" + + + + Always include how to verify the task is complete: + + - Which tests to run + - What behavior to check + - What the output should look like + + + + Don't assume OpenHands knows project conventions. Explicitly mention: + + - File locations and naming conventions + - Coding patterns to follow + - Related files to reference + + + + Define what should and shouldn't change: + + - Which files are in scope + - Which APIs must remain stable + - What dependencies can be added + + + +## By Use Case Type + +### Code Migrations + +**Goal:** Transform code from one pattern, language, or framework to another. + + + + - Migrate one file or module at a time + - Provide before/after examples + - Include the migration checklist + - Test after each migration step + - Preserve existing functionality + + + - Migrate entire codebase at once + - Skip verification steps + - Change behavior during migration + - Ignore edge cases + + + +**Example instruction:** + +```markdown +Migrate src/utils/helpers.js from JavaScript to TypeScript. + +Pattern to follow (see src/utils/format.ts for reference): +- Add explicit type annotations +- Use interfaces for object shapes +- Export types alongside functions + +Checklist: +- [ ] File renamed to .ts +- [ ] All functions have parameter types +- [ ] Return types are explicit +- [ ] No 'any' types used +- [ ] Imports updated in dependent files +- [ ] npx tsc --noEmit passes +``` + +### Test Coverage + +**Goal:** Add tests to existing code to improve reliability. + + + + - Focus on one module at a time + - Include happy path and error cases + - Specify the testing framework and patterns + - Point to existing test examples + - Cover edge cases + + + - Write tests for everything at once + - Skip edge cases + - Use different patterns than existing tests + - Forget to mock external dependencies + + + +**Example instruction:** + +```markdown +Add unit tests for the OrderService class. + +File: tests/services/test_order_service.py +Follow pattern in: tests/services/test_user_service.py + +Test cases needed: +1. create_order() - valid order creation +2. create_order() - missing required fields +3. create_order() - invalid product ID +4. get_order() - existing order +5. get_order() - non-existent order +6. cancel_order() - successful cancellation +7. cancel_order() - already shipped order (should fail) + +Use fixtures from conftest.py for database mocking. +Target: 90%+ coverage for OrderService +``` + +### Bug Fixing + +**Goal:** Identify and fix issues in the codebase. + + + + - Include reproduction steps + - Describe expected vs actual behavior + - Point to relevant log entries or error messages + - Mention when the bug was introduced if known + - Request a regression test + + + - Describe symptoms without context + - Fix without understanding root cause + - Skip adding tests + - Make unrelated changes + + + +**Example instruction:** + +```markdown +Fix: Users can't checkout with more than 10 items + +Reproduction: +1. Add 11+ items to cart +2. Click "Checkout" +3. Error: "Cart validation failed" + +Expected: Checkout succeeds for any valid cart +Actual: Fails for carts with >10 items + +Suspected cause: Hardcoded limit in src/services/cart.py line 45 + +After fix: +- Add test for checkout with 100 items +- Verify existing tests still pass +``` + +### Documentation + +**Goal:** Generate or update project documentation. + + + + - Specify the documentation style + - Point to existing docs as examples + - Include all required sections + - Request examples and code snippets + - Define the audience + + + - Generate docs without structure + - Skip code examples + - Ignore existing documentation patterns + - Over-document simple functions + + + +**Example instruction:** + +```markdown +Add docstrings to all public functions in src/api/users.py + +Style: Google docstrings (see src/api/products.py for examples) + +Include: +- Brief description +- Args with types +- Returns with type +- Raises for exceptions +- Example usage for complex functions + +Skip: Private methods (prefixed with _) +``` + +### Refactoring + +**Goal:** Improve code structure without changing behavior. + + + + - Define the specific improvement + - Ensure tests exist before refactoring + - Make incremental changes + - Verify behavior is unchanged + - Keep commits focused + + + - Change functionality during refactor + - Refactor without test coverage + - Make too many changes at once + - Rename public APIs without migration plan + + + +**Example instruction:** + +```markdown +Refactor: Extract email sending logic into a service + +Current: Email sending is scattered across multiple controllers +Target: Centralized EmailService class + +Steps: +1. Create src/services/email_service.py +2. Move email logic from: + - src/controllers/user.py (send_welcome_email) + - src/controllers/order.py (send_confirmation) + - src/controllers/auth.py (send_reset_link) +3. Update controllers to use EmailService +4. Add interface for testing (mock injection) + +Constraints: +- No changes to email content +- No changes to when emails are sent +- All existing tests must pass +``` + +## Workflow Tips + +### Parallel Execution + +For large tasks, run multiple OpenHands sessions in parallel: + +``` +Session 1: Migrate src/components/Button.jsx +Session 2: Migrate src/components/Input.jsx +Session 3: Migrate src/components/Modal.jsx +``` + +### Iterative Refinement + +For complex tasks, iterate: + +1. Start with a basic implementation +2. Review and provide feedback +3. Request specific improvements +4. Verify and finalize + +### Using Skills + +Create [Skills](/overview/skills) to encode: + +- Project-specific conventions +- Common patterns +- Frequently used context + +This reduces repetition in your instructions. + +## Measuring Success + +Track these metrics to improve over time: + +| Metric | Target | +|--------|--------| +| Task completion rate | >90% | +| Tests passing after changes | 100% | +| Code review acceptance | >80% | +| Time saved vs manual | >50% | + + + Browse specific use case examples and templates + diff --git a/use-cases/examples/api-integration.mdx b/use-cases/examples/api-integration.mdx new file mode 100644 index 00000000..3c8162bd --- /dev/null +++ b/use-cases/examples/api-integration.mdx @@ -0,0 +1,108 @@ +--- +title: "API Integration" +sidebarTitle: "API Integration" +description: "Using OpenHands to integrate with external APIs" +--- + +# API Integration + +OpenHands can help implement integrations with external APIs and services. + +## Common Integration Tasks + +- Implementing SDK wrappers +- Building API clients +- Adding webhook handlers +- Data synchronization + +## Instruction Template + +```markdown +Integrate with [Service Name] API. + +## API Documentation +[Link to API docs or describe endpoints] + +## Requirements +1. [Endpoint/feature 1] +2. [Endpoint/feature 2] + +## Implementation Details +- Location: src/integrations/[service].py +- Authentication: [API key/OAuth/etc] +- Error handling: [requirements] + +## Configuration +- Store credentials in [location] +- Use existing HTTP client from [location] + +## Testing +- Mock external calls in tests +- Test error handling +``` + +## Example: Payment API + +### Request + +```markdown +Integrate Stripe payment processing. + +API Docs: https://stripe.com/docs/api + +Requirements: +1. Create payment intent +2. Confirm payment +3. Handle webhooks for payment events + +Implementation: +- Location: src/services/payment/stripe_service.py +- Use stripe-python SDK +- Follow existing service patterns in src/services/ + +Configuration: +- STRIPE_SECRET_KEY in environment +- STRIPE_WEBHOOK_SECRET for webhook verification + +Error Handling: +- Wrap Stripe exceptions in custom PaymentError +- Log all API calls for debugging +- Implement retry for transient failures + +Testing: +- Use Stripe test keys +- Mock webhook payloads +- Test all error scenarios +``` + +## Best Practices + + + + Create abstraction layers around external services + + + Implement comprehensive error handling + + + Mock external calls in unit tests + + + Never hardcode API keys or secrets + + + +## Integration Checklist + +- [ ] API client/wrapper created +- [ ] Error handling implemented +- [ ] Retry logic for transient failures +- [ ] Credentials stored securely +- [ ] Logging for debugging +- [ ] Unit tests with mocks +- [ ] Integration tests (optional) +- [ ] Documentation updated + + + Follow step-by-step integration tutorials + diff --git a/use-cases/examples/bug-fixing.mdx b/use-cases/examples/bug-fixing.mdx new file mode 100644 index 00000000..8391fb79 --- /dev/null +++ b/use-cases/examples/bug-fixing.mdx @@ -0,0 +1,135 @@ +--- +title: "Bug Fixing & Debugging" +sidebarTitle: "Bug Fixing" +description: "Using OpenHands to fix bugs and debug issues" +--- + +# Bug Fixing & Debugging + +OpenHands can help identify, diagnose, and fix bugs in your codebase. + +## Effective Bug Reports + +The key to successful bug fixing with OpenHands is providing clear context. + +### Essential Information + + + + What's happening vs what should happen + + + Exact steps to trigger the bug + + + Relevant configuration, versions, data + + + Error messages, logs, screenshots + + + +## Instruction Template + +```markdown +## Bug Description +[What is happening incorrectly] + +## Expected Behavior +[What should happen instead] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. [Observe the bug] + +## Error Message/Logs +``` +[Paste error messages here] +``` + +## Relevant Files +- [file path 1] +- [file path 2] + +## Additional Context +- When did this start happening? +- Was there a recent change that might have caused this? +- Does it happen consistently or intermittently? + +## Acceptance Criteria +- [ ] Bug no longer reproduces +- [ ] Regression test added +- [ ] All existing tests pass +``` + +## Example: API Error Bug + +### Bug Report + +```markdown +## Bug Description +The /api/users/search endpoint returns 500 error when search +query contains special characters like "&" or "?". + +## Expected Behavior +Should return filtered results or empty array, never 500 error. + +## Steps to Reproduce +1. Call GET /api/users/search?q=test&value +2. Observe 500 Internal Server Error + +## Error Log +``` +TypeError: Cannot read property 'toLowerCase' of undefined + at searchUsers (src/api/users.js:45) +``` + +## Relevant Files +- src/api/users.js (search endpoint) +- src/services/userSearch.js (search logic) + +## Acceptance Criteria +- [ ] Special characters in search work correctly +- [ ] Add input sanitization +- [ ] Add test for special character handling +``` + +### Fix Approach + +OpenHands will: +1. Identify the root cause (URL parsing issue) +2. Add proper input validation +3. Fix the search function +4. Add regression tests + +## Best Practices + + + + Narrow down where the bug occurs before asking for a fix. + + + Request a regression test to prevent the bug from returning. + + + Fix only the bug; avoid unrelated improvements. + + + Include verification steps in your request. + + + +## Types of Bugs + +| Bug Type | Information to Include | +|----------|----------------------| +| Crash/Error | Full stack trace, trigger conditions | +| Logic Error | Expected vs actual output | +| Performance | Metrics, profiling data | +| UI/UX | Screenshots, browser info | +| Data Issue | Sample data, database state | + + + Learn how to write effective bug reports + diff --git a/use-cases/examples/code-migrations.mdx b/use-cases/examples/code-migrations.mdx new file mode 100644 index 00000000..bbc9ea36 --- /dev/null +++ b/use-cases/examples/code-migrations.mdx @@ -0,0 +1,158 @@ +--- +title: "Code Migrations" +sidebarTitle: "Code Migrations" +description: "Using OpenHands for language and framework migrations" +--- + +# Code Migrations + +OpenHands excels at systematic code transformations, making it ideal for migration projects. + +## Common Migration Types + +### Language Migrations + +- JavaScript → TypeScript +- Python 2 → Python 3 +- Java 8 → Java 17+ +- CoffeeScript → JavaScript + +### Framework Migrations + +- React Class Components → Hooks +- Angular.js → Angular +- Express → Fastify +- jQuery → Vanilla JS + +### Pattern Migrations + +- Callbacks → Promises/Async-Await +- REST → GraphQL +- Monolith → Microservices patterns + +## Migration Workflow + + + + Identify all files that need migration and any dependencies + + + Order files by dependency graph (migrate dependencies first) + + + Migrate files one at a time with verification + + + Run tests and manual verification after each migration + + + +## Example: JavaScript to TypeScript + +### Instruction Template + +```markdown +Migrate [filename].js to TypeScript. + +## Requirements +1. Rename file to .ts/.tsx +2. Add type annotations to all: + - Function parameters + - Return types + - Variables where inference isn't clear +3. Create interfaces for object shapes +4. Fix any type errors + +## Reference +See [example-file].ts for the pattern to follow + +## Verification +- [ ] npx tsc --noEmit passes +- [ ] All tests pass +- [ ] No 'any' types except where explicitly needed +``` + +### Before + +```javascript +// src/utils/format.js +export function formatCurrency(amount, currency) { + const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: currency, + }); + return formatter.format(amount); +} + +export function formatDate(date, options) { + return new Date(date).toLocaleDateString('en-US', options); +} +``` + +### After + +```typescript +// src/utils/format.ts +interface CurrencyFormatOptions { + currency: string; + locale?: string; +} + +interface DateFormatOptions { + year?: 'numeric' | '2-digit'; + month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow'; + day?: 'numeric' | '2-digit'; +} + +export function formatCurrency( + amount: number, + currency: string, + locale: string = 'en-US' +): string { + const formatter = new Intl.NumberFormat(locale, { + style: 'currency', + currency, + }); + return formatter.format(amount); +} + +export function formatDate( + date: Date | string, + options?: DateFormatOptions, + locale: string = 'en-US' +): string { + return new Date(date).toLocaleDateString(locale, options); +} +``` + +## Best Practices + + + + Start with files that have no internal dependencies, then work up the dependency tree. + + + Focus only on the migration. Don't refactor or add features simultaneously. + + + Run type checking and tests after each file to catch issues early. + + + The goal is equivalent functionality, not improvement. + + + +## Parallel Migration + +For large codebases, migrate independent files in parallel: + +```markdown +# Run these in parallel sessions: +Session 1: Migrate src/utils/string.js +Session 2: Migrate src/utils/number.js +Session 3: Migrate src/utils/date.js +``` + + + Follow step-by-step migration tutorials + diff --git a/use-cases/examples/documentation.mdx b/use-cases/examples/documentation.mdx new file mode 100644 index 00000000..b281677a --- /dev/null +++ b/use-cases/examples/documentation.mdx @@ -0,0 +1,157 @@ +--- +title: "Documentation Generation" +sidebarTitle: "Documentation" +description: "Using OpenHands to generate and maintain documentation" +--- + +# Documentation Generation + +OpenHands can help create and maintain various types of documentation. + +## Documentation Types + +### Code Documentation + +- Docstrings and inline comments +- API documentation +- Type annotations + +### Project Documentation + +- README files +- Contributing guides +- Architecture docs + +### User Documentation + +- User guides +- Tutorials +- API references + +## Instruction Templates + +### Adding Docstrings + +```markdown +Add docstrings to all public functions in [file]. + +Style: [Google/NumPy/Sphinx] +Reference: [example file with desired style] + +Include: +- Brief description +- Parameters with types +- Return value with type +- Exceptions raised +- Example usage (for complex functions) +``` + +### README Generation + +```markdown +Generate a README.md for this project. + +Include: +- Project description +- Installation instructions +- Quick start guide +- Configuration options +- Contributing guidelines +- License information + +Reference existing docs in /docs for accuracy. +Follow the template in [example repo]. +``` + +## Example: API Documentation + +### Request + +```markdown +Generate API documentation for src/api/orders.py + +Format: Markdown file at docs/api/orders.md + +For each endpoint, include: +- HTTP method and path +- Description +- Request parameters/body +- Response format +- Error responses +- Example request/response + +Follow the format in docs/api/users.md +``` + +### Output + +```markdown +# Orders API + +## Create Order + +`POST /api/orders` + +Creates a new order for the authenticated user. + +### Request Body + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| items | array | Yes | List of order items | +| shipping_address | object | Yes | Delivery address | + +### Response + +```json +{ + "id": "ord_123", + "status": "pending", + "total": 99.99, + "created_at": "2024-01-15T10:30:00Z" +} +``` + +### Errors + +| Code | Description | +|------|-------------| +| 400 | Invalid request body | +| 401 | Not authenticated | +| 422 | Validation error | +``` + +## Best Practices + + + + Match existing documentation style + + + Documentation should match current code + + + Include working code examples + + + Update docs when code changes + + + +## Maintaining Documentation + +Use OpenHands to keep documentation in sync: + +```markdown +Update the API documentation for [endpoint] to reflect +the changes in PR #123. + +Changes to document: +- New optional parameter: `include_metadata` +- Updated response format (added `metadata` field) +- New error code 429 for rate limiting +``` + + + Learn how to get better documentation output + diff --git a/use-cases/examples/refactoring.mdx b/use-cases/examples/refactoring.mdx new file mode 100644 index 00000000..0c22fe44 --- /dev/null +++ b/use-cases/examples/refactoring.mdx @@ -0,0 +1,124 @@ +--- +title: "Code Refactoring" +sidebarTitle: "Refactoring" +description: "Using OpenHands for safe code refactoring" +--- + +# Code Refactoring + +OpenHands can help refactor code to improve quality while preserving functionality. + +## Refactoring Types + +### Structural Refactoring + +- Extract methods/functions +- Extract classes +- Move code to appropriate modules +- Reduce duplication + +### Pattern Refactoring + +- Apply design patterns +- Remove anti-patterns +- Improve code organization + +### Performance Refactoring + +- Optimize algorithms +- Reduce complexity +- Improve efficiency + +## Prerequisites + + +Before refactoring, ensure adequate test coverage exists to verify behavior is preserved. + + +## Instruction Template + +```markdown +## Current State +[Describe the current code structure/issue] + +## Desired State +[Describe the target structure] + +## Scope +Files to modify: [list] +Files NOT to modify: [list] + +## Constraints +- Maintain backward compatibility +- No changes to public APIs +- All tests must pass + +## Verification +[How to verify the refactoring succeeded] +``` + +## Example: Extract Service + +### Request + +```markdown +Extract email sending logic into a dedicated service. + +Current state: +- Email sending scattered across UserController, OrderController, AuthController +- Duplicate SMTP configuration in each location +- No consistent error handling + +Desired state: +- Single EmailService class +- Consistent error handling and logging +- Easy to mock for testing + +Files to modify: +- Create: src/services/email_service.py +- Update: src/controllers/user.py +- Update: src/controllers/order.py +- Update: src/controllers/auth.py + +Constraints: +- Don't change email content +- Don't change when emails are sent +- Maintain existing function signatures + +Verification: +- All existing tests pass +- New unit tests for EmailService +- Manual test: trigger each email type +``` + +## Best Practices + + + + Make incremental changes, verifying after each step. + + + Ensure tests exist before refactoring. + + + Refactoring changes structure, not behavior. + + + Define exactly what should and shouldn't change. + + + +## Common Refactoring Tasks + +| Task | Good For | +|------|----------| +| Extract Method | Long functions with distinct sections | +| Extract Class | Classes with multiple responsibilities | +| Move Method | Method in wrong class | +| Rename | Unclear naming | +| Replace Conditional with Polymorphism | Complex if/else chains | +| Introduce Parameter Object | Functions with many parameters | + + + More tips for successful refactoring + diff --git a/use-cases/examples/test-coverage.mdx b/use-cases/examples/test-coverage.mdx new file mode 100644 index 00000000..e62433e5 --- /dev/null +++ b/use-cases/examples/test-coverage.mdx @@ -0,0 +1,211 @@ +--- +title: "Test Coverage" +sidebarTitle: "Test Coverage" +description: "Using OpenHands to improve test coverage" +--- + +# Improving Test Coverage + +OpenHands can systematically add tests to your codebase, improving reliability and enabling safe refactoring. + +## When to Use This + +- **Legacy code** without tests +- **New features** needing test coverage +- **Critical paths** requiring additional verification +- **Pre-refactoring** to ensure behavior is captured + +## Test Types + +### Unit Tests + +Test individual functions or methods in isolation. + +```markdown +Add unit tests for the validateEmail() function in src/utils/validation.js + +Test cases: +1. Valid email formats (user@domain.com) +2. Invalid formats (missing @, invalid TLD) +3. Edge cases (empty string, null, undefined) +4. International characters +``` + +### Integration Tests + +Test component interactions. + +```markdown +Add integration tests for the user registration flow. + +Test the complete path: +1. POST /api/register with valid data +2. Verify user created in database +3. Verify welcome email sent +4. Verify response structure +``` + +### Component Tests (Frontend) + +Test UI components. + +```markdown +Add tests for the LoginForm component. + +Test: +1. Renders all required fields +2. Shows validation errors on submit with empty fields +3. Calls onSubmit with form data when valid +4. Disables submit button while loading +``` + +## Instruction Templates + +### Unit Test Template + +```markdown +Add unit tests for [function/class] in [file]. + +Location: [test file path] +Framework: [jest/pytest/etc] +Follow pattern in: [example test file] + +Test cases: +1. [Happy path description] +2. [Error case 1] +3. [Error case 2] +4. [Edge case] + +Coverage target: [X]% +``` + +### Integration Test Template + +```markdown +Add integration tests for [feature/endpoint]. + +Location: [test file path] +Setup: [database/mocks needed] + +Test scenarios: +1. [Scenario 1 - expected flow] +2. [Scenario 2 - error handling] +3. [Scenario 3 - edge case] + +Assertions: +- [What to verify] +``` + +## Example: Adding Unit Tests + +### Task + +```markdown +Add unit tests for the OrderCalculator class. + +File: tests/unit/test_order_calculator.py +Class: src/services/order_calculator.py + +Test cases for calculate_total(): +1. Single item order +2. Multiple items +3. Empty order (should return 0) +4. Order with discount code +5. Order with quantity > 1 of same item + +Test cases for apply_discount(): +1. Valid percentage discount +2. Valid fixed amount discount +3. Invalid discount code (should raise) +4. Expired discount (should raise) + +Use pytest fixtures from conftest.py for test data. +Mock the DiscountService for discount tests. +``` + +### Output + +```python +import pytest +from unittest.mock import Mock, patch +from src.services.order_calculator import OrderCalculator +from src.models import Order, OrderItem + + +class TestOrderCalculator: + @pytest.fixture + def calculator(self): + return OrderCalculator() + + @pytest.fixture + def sample_items(self): + return [ + OrderItem(product_id=1, price=10.00, quantity=1), + OrderItem(product_id=2, price=25.00, quantity=2), + ] + + def test_calculate_total_single_item(self, calculator): + items = [OrderItem(product_id=1, price=10.00, quantity=1)] + assert calculator.calculate_total(items) == 10.00 + + def test_calculate_total_multiple_items(self, calculator, sample_items): + # 10 + (25 * 2) = 60 + assert calculator.calculate_total(sample_items) == 60.00 + + def test_calculate_total_empty_order(self, calculator): + assert calculator.calculate_total([]) == 0.00 + + @patch('src.services.order_calculator.DiscountService') + def test_apply_discount_percentage(self, mock_discount, calculator): + mock_discount.get_discount.return_value = { + 'type': 'percentage', + 'value': 10 + } + result = calculator.apply_discount(100.00, 'SAVE10') + assert result == 90.00 + + @patch('src.services.order_calculator.DiscountService') + def test_apply_discount_invalid_code(self, mock_discount, calculator): + mock_discount.get_discount.side_effect = ValueError('Invalid code') + with pytest.raises(ValueError, match='Invalid code'): + calculator.apply_discount(100.00, 'INVALID') +``` + +## Best Practices + + + + Follow the testing patterns already in the codebase + + + Focus on what the code does, not how it does it + + + Test boundaries, empty inputs, and error conditions + + + Test names should describe the scenario being tested + + + +## Coverage Strategies + +### By Module + +```markdown +Week 1: src/services/ (critical business logic) +Week 2: src/api/ (endpoint handlers) +Week 3: src/utils/ (helper functions) +``` + +### By Criticality + +1. Payment processing +2. Authentication +3. Data validation +4. Business rules +5. UI components + + + Follow a step-by-step tutorial + diff --git a/use-cases/overview.mdx b/use-cases/overview.mdx new file mode 100644 index 00000000..6cd01158 --- /dev/null +++ b/use-cases/overview.mdx @@ -0,0 +1,109 @@ +--- +title: "Use Cases Overview" +sidebarTitle: "Overview" +description: "Explore proven use cases and examples for OpenHands" +--- + +# Use Cases Overview + +Discover how teams use OpenHands to accelerate development, improve code quality, and automate engineering workflows. + +## What Makes a Good Use Case + +The best tasks for OpenHands are: + + + + Tasks with well-defined boundaries and acceptance criteria + + + Results that can be validated through tests or inspection + + + Patterns that can be applied across multiple files or projects + + + Sufficient context available in the codebase or instructions + + + +## Popular Use Cases + +### Code Migrations & Modernization + +OpenHands excels at systematic code transformations: + + + + Language and framework migrations + + + Code cleanup and restructuring + + + +### Quality & Testing + +Improve code quality and test coverage: + + + + Adding tests to existing code + + + Debugging and fixing issues + + + +### Development Workflows + +Streamline common development tasks: + + + + Generate and maintain docs + + + Working with external APIs + + + +## Success Stories + +Teams using OpenHands effectively report: + +- **50-70% reduction** in time spent on repetitive tasks +- **Faster onboarding** with automated code understanding +- **Improved test coverage** through systematic test generation +- **Reduced technical debt** via automated refactoring + +## Getting Started + + + + Browse the [use cases](/use-cases/examples/code-migrations) to find one that matches your needs + + + Work through a [tutorial](/use-cases/tutorials/getting-started) to learn the patterns + + + Find ready-to-use [prompts](/use-cases/prompts/testing-refactoring) for common tasks + + + Create [Skills](/overview/skills) to encode project-specific context + + + +## Best Practices + +For the best results: + +1. **Start small**: Begin with simple, well-defined tasks +2. **Provide context**: Include relevant background information +3. **Set clear criteria**: Define what "done" looks like +4. **Verify results**: Always review and test the output +5. **Iterate**: Refine your approach based on results + + + Learn detailed best practices for each use case type + diff --git a/use-cases/prompts/data-analysis.mdx b/use-cases/prompts/data-analysis.mdx new file mode 100644 index 00000000..4145cd72 --- /dev/null +++ b/use-cases/prompts/data-analysis.mdx @@ -0,0 +1,256 @@ +--- +title: "Data & Analysis Prompts" +sidebarTitle: "Data & Analysis" +description: "Ready-to-use prompts for data processing and analysis tasks" +--- + +# Data & Analysis Prompts + +Copy and customize these prompts for data processing and analysis tasks. + +## Data Processing Prompts + +### Create Data Pipeline + +```markdown +Create a data pipeline to process [data_source]. + +Input: [file format, API endpoint, database table] +Output: [destination and format] + +Processing steps: +1. Extract from [source] +2. Validate [validation rules] +3. Transform [transformations needed] +4. Load to [destination] + +Error handling: +- Log invalid records +- Continue on non-critical errors +- Fail fast on critical issues + +Add tests with sample data. +``` + +### Data Validation + +```markdown +Add data validation for [model/schema]. + +Validate: +- Required fields: [list] +- Format validations: [email, phone, etc] +- Range validations: [min/max values] +- Custom rules: [business logic] + +On validation failure: +- Return specific error messages +- Include field name and invalid value +- Support multiple errors per record +``` + +### CSV/JSON Processing + +```markdown +Create a utility to process [file_type] files. + +Features: +- Read large files efficiently (streaming) +- Handle encoding issues +- Skip header row (configurable) +- Map columns to model + +Input: [file path or file object] +Output: [list of objects, generator, etc] + +Include: +- Progress callback for large files +- Error handling for malformed rows +- Type conversion (strings to dates, numbers) +``` + +## Analysis Prompts + +### Generate Report + +```markdown +Create a report generator for [report_name]. + +Data sources: +- [source 1] +- [source 2] + +Metrics to calculate: +- [metric 1]: [formula/logic] +- [metric 2]: [formula/logic] +- [metric 3]: [formula/logic] + +Output format: [PDF/HTML/JSON] + +Include: +- Summary statistics +- Trends over time +- Comparison with previous period +``` + +### Data Aggregation + +```markdown +Create aggregation functions for [data_type]. + +Aggregations needed: +1. Group by [field] and calculate: + - Count + - Sum of [amount_field] + - Average of [value_field] + +2. Time-based aggregation: + - Daily/Weekly/Monthly totals + - Running averages + - Period-over-period comparison + +Output as [DataFrame/dict/JSON]. +``` + +### Statistical Analysis + +```markdown +Add statistical analysis to [data_module]. + +Calculate: +- Descriptive stats (mean, median, std, min, max) +- Distribution analysis +- Correlation between [field1] and [field2] +- Outlier detection + +Visualization: +- Histogram for distribution +- Scatter plot for correlation +- Box plot for outliers + +Use [pandas/numpy/scipy] following project conventions. +``` + +## Database Prompts + +### Write SQL Query + +```markdown +Write a SQL query to [objective]. + +Tables involved: +- [table1]: [columns] +- [table2]: [columns] + +Requirements: +- [filter conditions] +- [join logic] +- [grouping/aggregation] +- [sorting] + +Performance considerations: +- Use indexes on [fields] +- Limit results to [N] +- Avoid full table scans +``` + +### Database Migration + +```markdown +Create a database migration for [change]. + +Changes: +- Add column: [column_name] [type] to [table] +- Modify column: [changes] +- Add index on: [columns] +- Create table: [schema] + +Include: +- Up migration +- Down migration (rollback) +- Data migration script if needed + +Test with sample data before and after. +``` + +### Query Optimization + +```markdown +Optimize this slow query: + +```sql +[paste query] +``` + +Current performance: [time/rows scanned] +Target: [desired performance] + +Analyze: +- Missing indexes +- Inefficient joins +- Subquery vs join opportunities +- Query plan analysis + +Provide optimized query and explanation. +``` + +## Data Integration Prompts + +### API Data Sync + +```markdown +Create a sync job for [external_api] data. + +API details: +- Endpoint: [url] +- Auth: [method] +- Rate limit: [requests/minute] + +Sync logic: +- Full sync: [when/how] +- Incremental sync: [based on timestamp/id] +- Conflict resolution: [strategy] + +Error handling: +- Retry on transient errors +- Log permanent failures +- Alert on threshold exceeded +``` + +### ETL Script + +```markdown +Create an ETL script for [data_source] to [destination]. + +Extract: +- Source: [database/API/file] +- Query/Filter: [conditions] +- Frequency: [schedule] + +Transform: +- [transformation 1] +- [transformation 2] +- Data cleaning rules + +Load: +- Destination: [target] +- Mode: [insert/upsert/replace] +- Batch size: [number] + +Add logging for monitoring and debugging. +``` + +## Quick Reference + +| Task | Key Elements | +|------|--------------| +| Pipeline | Source, destination, steps, error handling | +| Validation | Rules, error messages, failure handling | +| Report | Data sources, metrics, output format | +| SQL | Tables, joins, filters, performance | +| Migration | Changes, up/down scripts, data migration | +| ETL | Extract source, transforms, load destination | + + + Learn how to structure data tasks effectively + diff --git a/use-cases/prompts/testing-refactoring.mdx b/use-cases/prompts/testing-refactoring.mdx new file mode 100644 index 00000000..2000c892 --- /dev/null +++ b/use-cases/prompts/testing-refactoring.mdx @@ -0,0 +1,213 @@ +--- +title: "Testing & Refactoring Prompts" +sidebarTitle: "Testing & Refactoring" +description: "Ready-to-use prompts for testing and refactoring tasks" +--- + +# Testing & Refactoring Prompts + +Copy and customize these prompts for common testing and refactoring tasks. + +## Unit Testing Prompts + +### Add Unit Tests to a Function + +```markdown +Add unit tests for the [function_name] function in [file_path]. + +Test cases to cover: +1. Happy path with valid input +2. Edge case: empty input +3. Edge case: null/undefined input +4. Error case: invalid input type +5. Boundary conditions + +Framework: [pytest/jest/etc] +Location: [test_file_path] +Follow patterns in: [example_test_file] +``` + +### Increase Test Coverage + +```markdown +Increase test coverage for [module_name] from [current]% to [target]%. + +Priority order: +1. Untested public methods +2. Error handling paths +3. Edge cases in existing tests +4. Integration points + +Generate a coverage report first, then add tests for uncovered lines. +``` + +### Add Integration Tests + +```markdown +Add integration tests for the [feature] workflow. + +Test the complete flow: +1. [Step 1] +2. [Step 2] +3. [Step 3] + +Setup requirements: +- Test database with seed data +- Mock external services: [list] + +Assertions: +- Database state after each step +- API response formats +- Side effects (emails, events, etc.) +``` + +## Refactoring Prompts + +### Extract Method + +```markdown +Extract the code block at lines [X-Y] in [file] into a new method. + +New method: +- Name: [method_name] +- Parameters: [infer from extracted code] +- Return type: [infer or specify] + +Requirements: +- Update original code to call new method +- Add docstring to new method +- All tests must pass +``` + +### Extract Class + +```markdown +Extract [responsibility] from [class_name] into a new class. + +New class: [NewClassName] +Location: [file_path] + +Move these methods: +- [method1] +- [method2] + +Move these properties: +- [property1] +- [property2] + +Update [OriginalClass] to use [NewClassName] via composition. +Maintain backward compatibility. +``` + +### Reduce Duplication + +```markdown +Identify and eliminate code duplication in [module/directory]. + +Analysis: +1. Find duplicate or near-duplicate code blocks +2. Identify common patterns that should be abstracted + +Actions: +1. Create shared utility functions +2. Extract common base classes if appropriate +3. Update all usages to use shared code +4. Ensure all tests pass +``` + +### Improve Error Handling + +```markdown +Improve error handling in [file/module]. + +Current issues: +- Generic exceptions caught everywhere +- Errors not logged properly +- Missing error recovery + +Requirements: +1. Create specific exception classes +2. Add proper try/catch blocks +3. Log errors with context +4. Implement graceful degradation where possible +5. Update tests to verify error handling +``` + +### Apply Design Pattern + +```markdown +Refactor [code_area] to use the [Pattern] pattern. + +Current implementation: +[Describe current approach] + +Target: +Apply [Strategy/Factory/Observer/etc] pattern to: +- [Benefit 1] +- [Benefit 2] + +Constraints: +- Maintain existing public API +- All tests must pass +- Add tests for new pattern usage +``` + +## Code Quality Prompts + +### Add Type Annotations + +```markdown +Add type annotations to all functions in [file]. + +Requirements: +- Parameter types +- Return types +- Generic types where appropriate +- No 'any' types unless necessary + +Verify with: [mypy/tsc --noEmit] +``` + +### Add Docstrings + +```markdown +Add docstrings to all public functions/classes in [file]. + +Style: [Google/NumPy/JSDoc] + +Include: +- Brief description +- Parameters with types +- Return value +- Exceptions raised +- Example usage (for complex functions) +``` + +### Improve Naming + +```markdown +Review and improve naming in [file/module]. + +Check: +- Variables: descriptive, not abbreviated +- Functions: verb-based, clear purpose +- Classes: noun-based, single responsibility +- Constants: UPPER_CASE with clear meaning + +Rename anything unclear, updating all references. +``` + +## Quick Reference + +| Task | Key Elements to Include | +|------|------------------------| +| Unit test | Function, test cases, framework, location | +| Integration test | Workflow steps, setup, assertions | +| Extract method | Code location, new name, requirements | +| Extract class | Methods to move, new class details | +| Error handling | Current issues, desired behavior | +| Type annotations | File, verification command | + + + Learn how to customize these prompts effectively + diff --git a/use-cases/prompts/web-development.mdx b/use-cases/prompts/web-development.mdx new file mode 100644 index 00000000..85312afd --- /dev/null +++ b/use-cases/prompts/web-development.mdx @@ -0,0 +1,278 @@ +--- +title: "Web Development Prompts" +sidebarTitle: "Web Development" +description: "Ready-to-use prompts for web development tasks" +--- + +# Web Development Prompts + +Copy and customize these prompts for frontend and full-stack web development tasks. + +## Component Prompts + +### Create UI Component + +```markdown +Create a [ComponentName] component. + +Location: src/components/[ComponentName]/[ComponentName].tsx + +Props: +- [prop1]: [type] - [description] +- [prop2]: [type] - [description] +- [prop3]?: [type] - [optional, default: value] + +Features: +- [Feature 1] +- [Feature 2] + +Styling: [Tailwind/CSS Modules/styled-components] +Follow patterns in: src/components/[ExampleComponent] + +Include: +- TypeScript interfaces +- Default props +- Unit tests +- Storybook story (if applicable) +``` + +### Create Form Component + +```markdown +Create a form for [purpose]. + +Location: src/components/forms/[FormName].tsx + +Fields: +- [field1]: [type] - [validation rules] +- [field2]: [type] - [validation rules] +- [field3]: [type] - [validation rules] + +Behavior: +- Validation on blur and submit +- Error messages under fields +- Loading state on submit +- Success/error callbacks + +Use: [react-hook-form/formik/etc] +Validation: [zod/yup/etc] +``` + +### Create Modal/Dialog + +```markdown +Create a modal component for [purpose]. + +Props: +- isOpen: boolean +- onClose: () => void +- title: string +- [additional props] + +Features: +- Close on backdrop click +- Close on Escape key +- Focus trap inside modal +- Animated open/close +- Accessible (ARIA) + +Content: [describe content/children] +Actions: [button labels and behaviors] +``` + +## Page Prompts + +### Create Page/Route + +```markdown +Create the [PageName] page. + +Route: /[path] +Location: src/pages/[PageName]/[PageName].tsx + +Sections: +1. [Section 1 description] +2. [Section 2 description] +3. [Section 3 description] + +Data requirements: +- Fetch from: [API endpoint] +- State management: [local/context/store] + +Features: +- Loading skeleton +- Error state +- Empty state +- Responsive layout +``` + +### Create Dashboard Page + +```markdown +Create a dashboard page showing [overview]. + +Sections: +1. Summary cards: [metrics to show] +2. Charts: [chart types and data] +3. Recent activity: [list of items] +4. Quick actions: [buttons/links] + +Data sources: +- [endpoint 1] for [data] +- [endpoint 2] for [data] + +Refresh: [auto-refresh interval or manual] +``` + +## API Prompts + +### Create API Endpoint + +```markdown +Create a REST endpoint for [resource]. + +Method: [GET/POST/PUT/DELETE] +Path: /api/[path] +Location: src/api/[handler].ts + +Request: +- Headers: [auth requirements] +- Body: [schema if applicable] +- Query params: [parameters] + +Response: +- Success: [status code, body schema] +- Errors: [error codes and messages] + +Include: +- Input validation +- Error handling +- Rate limiting (if applicable) +- Tests +``` + +### Create API Client + +```markdown +Create an API client for [service]. + +Location: src/services/[ServiceName]Client.ts + +Methods: +- [method1]: [description, params, return] +- [method2]: [description, params, return] +- [method3]: [description, params, return] + +Features: +- TypeScript types for all requests/responses +- Error handling with custom exceptions +- Request/response interceptors +- Retry logic for transient failures +- Request cancellation support + +Base URL: [from environment config] +Auth: [token/API key handling] +``` + +## State Management Prompts + +### Create Store/Context + +```markdown +Create state management for [feature]. + +Location: src/store/[feature].ts + +State: +- [property1]: [type] +- [property2]: [type] + +Actions: +- [action1]: [description] +- [action2]: [description] + +Use: [zustand/redux/context] +Follow patterns in: src/store/[existing_store] + +Include persistence to localStorage for: [which state] +``` + +### Add Data Fetching + +```markdown +Add data fetching for [resource] with caching. + +Hook: src/hooks/use[Resource].ts + +Features: +- Fetch data from [endpoint] +- Cache with [react-query/SWR/etc] +- Automatic refetch on window focus +- Optimistic updates for mutations +- Loading and error states + +Types: Define TypeScript interfaces for response data. +``` + +## Styling Prompts + +### Add Responsive Styles + +```markdown +Make [component/page] responsive. + +Breakpoints: +- Mobile: < 640px +- Tablet: 640-1024px +- Desktop: > 1024px + +Mobile changes: +- [change 1] +- [change 2] + +Tablet changes: +- [change 1] +- [change 2] + +Test on: [specific devices/dimensions] +``` + +### Create Theme/Design Tokens + +```markdown +Create design tokens for the application. + +Location: src/styles/tokens.ts + +Colors: +- Primary: [hex values for shades] +- Secondary: [hex values] +- Neutral: [gray scale] +- Semantic: success, warning, error, info + +Typography: +- Font families +- Font sizes +- Line heights +- Font weights + +Spacing: +- Scale (4, 8, 12, 16, 24, 32, 48, 64) + +Export for use with [Tailwind/CSS-in-JS/etc] +``` + +## Quick Reference + +| Task | Key Elements | +|------|--------------| +| Component | Props, features, styling, tests | +| Form | Fields, validation, submit handling | +| Page | Sections, data, states | +| API | Method, path, request/response, errors | +| State | Properties, actions, persistence | +| Styling | Breakpoints, changes per size | + + + See full frontend development tutorials + diff --git a/use-cases/tutorials/containerization.mdx b/use-cases/tutorials/containerization.mdx new file mode 100644 index 00000000..0d7432f2 --- /dev/null +++ b/use-cases/tutorials/containerization.mdx @@ -0,0 +1,224 @@ +--- +title: "Containerize an Application" +sidebarTitle: "Containerization" +description: "Tutorial: Dockerize an application with OpenHands" +--- + +# Tutorial: Containerize an Application + +Learn how to use OpenHands to containerize an existing application with Docker. + +## Prerequisites + +- Existing application to containerize +- Docker installed locally +- OpenHands CLI or Cloud access + +## What We'll Create + +- Optimized Dockerfile +- Docker Compose configuration +- Development and production setups +- CI/CD integration + +## Step 1: Analyze the Application + +First, have OpenHands analyze your app: + +```markdown +Analyze this application and determine containerization requirements. + +Check: +1. Language/runtime requirements +2. Dependencies and build steps +3. Environment variables needed +4. Ports to expose +5. External service dependencies (database, cache, etc.) +6. Static files or assets + +Output a containerization plan. +``` + +## Step 2: Create the Dockerfile + +```markdown +Create an optimized Dockerfile for this application. + +Requirements: +- Multi-stage build for smaller image +- Non-root user for security +- Proper layer caching +- Health check endpoint + +Application details: +- Python 3.11 / Node 18 / etc. +- Dependencies in requirements.txt / package.json +- Entry point: [command] +- Port: [port] + +Follow best practices: +- Pin base image versions +- Minimize layers +- Copy requirements before source code +- Use .dockerignore +``` + +### Example Output (Python) + +```dockerfile +# Build stage +FROM python:3.11-slim as builder + +WORKDIR /app + +# Install build dependencies +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential \ + && rm -rf /var/lib/apt/lists/* + +# Install Python dependencies +COPY requirements.txt . +RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels -r requirements.txt + +# Production stage +FROM python:3.11-slim + +WORKDIR /app + +# Create non-root user +RUN useradd --create-home --shell /bin/bash app +USER app + +# Install dependencies from wheels +COPY --from=builder /app/wheels /wheels +RUN pip install --no-cache-dir /wheels/* + +# Copy application code +COPY --chown=app:app . . + +EXPOSE 8000 + +HEALTHCHECK --interval=30s --timeout=3s \ + CMD curl -f http://localhost:8000/health || exit 1 + +CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] +``` + +## Step 3: Create Docker Compose + +```markdown +Create docker-compose.yml for local development. + +Include: +- Application service +- Database (PostgreSQL) +- Redis (if used) +- Volume mounts for hot reload +- Environment file support + +Development features: +- Source code mounted as volume +- Debug mode enabled +- Exposed ports for debugging +``` + +### Example Output + +```yaml +version: '3.8' + +services: + app: + build: + context: . + dockerfile: Dockerfile + ports: + - "8000:8000" + volumes: + - .:/app + environment: + - DATABASE_URL=postgresql://user:pass@db:5432/app + - REDIS_URL=redis://redis:6379 + depends_on: + - db + - redis + + db: + image: postgres:15 + environment: + POSTGRES_USER: user + POSTGRES_PASSWORD: pass + POSTGRES_DB: app + volumes: + - postgres_data:/var/lib/postgresql/data + + redis: + image: redis:7-alpine + +volumes: + postgres_data: +``` + +## Step 4: Add Production Configuration + +```markdown +Create production docker-compose configuration. + +Differences from development: +- No volume mounts (use built image) +- Production environment variables +- Resource limits +- Restart policies +- Logging configuration +``` + +## Step 5: Test the Container + +Verify the containerized application: + +```bash +# Build +docker-compose build + +# Run +docker-compose up -d + +# Check logs +docker-compose logs -f app + +# Test health +curl http://localhost:8000/health + +# Run tests in container +docker-compose exec app pytest +``` + +## Best Practices + + + + Keep production images small by separating build and runtime stages. + + + Create and use a non-root user for security. + + + Copy dependency files before source code for better caching. + + + Enable orchestrators to monitor container health. + + + +## Common Issues + +| Issue | Solution | +|-------|----------| +| Large image size | Use multi-stage builds, slim base images | +| Slow builds | Optimize layer ordering for caching | +| Permission errors | Check user permissions, file ownership | +| Connection refused | Verify port mappings, network configuration | + + + Explore other tutorials + diff --git a/use-cases/tutorials/frontend-development.mdx b/use-cases/tutorials/frontend-development.mdx new file mode 100644 index 00000000..b2ad3cfb --- /dev/null +++ b/use-cases/tutorials/frontend-development.mdx @@ -0,0 +1,198 @@ +--- +title: "Frontend Development" +sidebarTitle: "Frontend Development" +description: "Tutorial: Build frontend features with OpenHands" +--- + +# Tutorial: Frontend Development + +Learn how to use OpenHands for frontend development tasks including components, features, and UI improvements. + +## Prerequisites + +- Frontend project (React, Vue, Angular, etc.) +- OpenHands CLI or Cloud access +- Basic frontend knowledge + +## Common Frontend Tasks + + + + Build reusable UI components + + + Implement complete features + + + Add styling and responsive design + + + Manage application state + + + +## Example 1: Build a Component + +### Task: Create a Data Table Component + +```markdown +Create a reusable DataTable component. + +Location: src/components/DataTable/DataTable.tsx + +Features: +- Accept data array and column configuration +- Sortable columns (click header to sort) +- Pagination with configurable page size +- Loading and empty states +- Responsive design + +Props interface: +```typescript +interface DataTableProps { + data: T[]; + columns: Column[]; + pageSize?: number; + loading?: boolean; + onRowClick?: (row: T) => void; +} +``` + +Styling: +- Use existing Tailwind classes +- Follow patterns in src/components/Card + +Tests: +- Renders with data +- Sorting works +- Pagination works +- Shows loading state +- Shows empty state +``` + +## Example 2: Implement a Feature + +### Task: Add Search Functionality + +```markdown +Add search/filter functionality to the products page. + +Location: src/pages/Products/Products.tsx + +Requirements: +1. Search input in the header area +2. Debounced search (300ms delay) +3. Filter by: name, category, price range +4. Clear filters button +5. Persist filters in URL params +6. Loading state while filtering + +UI/UX: +- Search icon in input +- Show active filter count +- Animate filter panel open/close + +Use existing hooks: +- useDebounce from src/hooks +- useQueryParams for URL sync +``` + +## Example 3: Responsive Design + +### Task: Make Dashboard Mobile-Friendly + +```markdown +Make the dashboard responsive for mobile devices. + +File: src/pages/Dashboard/Dashboard.tsx + +Current issues: +- Cards overflow on small screens +- Navigation not usable on mobile +- Charts too small to read + +Requirements: +1. Stack cards vertically on mobile +2. Collapsible sidebar navigation +3. Touch-friendly chart interactions +4. Readable font sizes + +Breakpoints: +- Mobile: < 640px +- Tablet: 640px - 1024px +- Desktop: > 1024px + +Test on: +- iPhone SE (375px) +- iPad (768px) +- Desktop (1440px) +``` + +## Example 4: State Management + +### Task: Add Shopping Cart State + +```markdown +Implement shopping cart state management. + +State requirements: +- Items in cart (product, quantity) +- Cart total (with discounts) +- Persist to localStorage +- Sync across tabs + +Actions: +- addItem(product, quantity) +- removeItem(productId) +- updateQuantity(productId, quantity) +- clearCart() +- applyDiscount(code) + +Location: +- Store: src/store/cart.ts +- Hook: src/hooks/useCart.ts + +Use Zustand following patterns in src/store/user.ts +``` + +## Frontend Best Practices + + + + - Single responsibility + - Props for customization + - Sensible defaults + - TypeScript interfaces + + + - Memoize expensive computations + - Lazy load routes/components + - Optimize re-renders + - Use proper keys in lists + + + - Semantic HTML + - ARIA labels + - Keyboard navigation + - Color contrast + + + - Unit tests for logic + - Component tests for rendering + - E2E for critical flows + + + +## Tips for Frontend Tasks + +| Do | Don't | +|----|-------| +| Specify design system/patterns | Assume styling approach | +| Include responsive requirements | Ignore mobile | +| Reference existing components | Create from scratch unnecessarily | +| Specify state management approach | Leave state undefined | +| Include accessibility requirements | Skip a11y | + + + Explore other tutorials + diff --git a/use-cases/tutorials/getting-started.mdx b/use-cases/tutorials/getting-started.mdx new file mode 100644 index 00000000..4dbbfea7 --- /dev/null +++ b/use-cases/tutorials/getting-started.mdx @@ -0,0 +1,133 @@ +--- +title: "Getting Started with Tutorials" +sidebarTitle: "Getting Started" +description: "Learn OpenHands through hands-on tutorials" +--- + +# Getting Started with Tutorials + +These tutorials will help you learn OpenHands by working through practical examples. + +## Tutorial Structure + +Each tutorial follows this pattern: + + + + Prerequisites and environment setup + + + Clear description of what we'll build + + + Step-by-step instructions for OpenHands + + + How to test the results + + + +## Available Tutorials + + + + Create a complete REST API from scratch + + + Add comprehensive tests to existing code + + + Package an application with Docker + + + Build UI components and features + + + +## Your First Tutorial + +Start with this simple task to get familiar with OpenHands: + +### Task: Add a Utility Function + +```markdown +Create a utility function that validates email addresses. + +Location: src/utils/validation.py + +Requirements: +1. Function name: validate_email +2. Accept a string parameter +3. Return True if valid email format, False otherwise +4. Handle edge cases (empty string, None) + +Add tests in: tests/utils/test_validation.py + +Test cases: +- Valid emails (user@domain.com, user+tag@domain.co.uk) +- Invalid emails (missing @, no domain, etc.) +- Edge cases (empty, None, whitespace) +``` + +### Expected Outcome + +OpenHands will create: + +1. **The validation function:** +```python +# src/utils/validation.py +import re + +def validate_email(email: str | None) -> bool: + """Validate email address format.""" + if not email or not isinstance(email, str): + return False + pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + return bool(re.match(pattern, email.strip())) +``` + +2. **Tests:** +```python +# tests/utils/test_validation.py +import pytest +from src.utils.validation import validate_email + +class TestValidateEmail: + def test_valid_email(self): + assert validate_email("user@example.com") is True + + def test_invalid_email_no_at(self): + assert validate_email("userexample.com") is False + + def test_empty_string(self): + assert validate_email("") is False + + def test_none(self): + assert validate_email(None) is False +``` + +## Tips for Success + + + + Make sure you understand all requirements before starting. + + + Test each step before moving to the next. + + + If something isn't working, provide feedback to OpenHands. + + + +## Next Steps + +Choose a tutorial based on your goals: + +- **Learning OpenHands**: Start with [Build a REST API](/use-cases/tutorials/rest-api) +- **Improving existing code**: Try [Add Test Coverage](/use-cases/tutorials/test-coverage) +- **DevOps tasks**: Go to [Containerization](/use-cases/tutorials/containerization) + + + More project ideas to try with OpenHands + diff --git a/use-cases/tutorials/rest-api.mdx b/use-cases/tutorials/rest-api.mdx new file mode 100644 index 00000000..8de6fbf4 --- /dev/null +++ b/use-cases/tutorials/rest-api.mdx @@ -0,0 +1,173 @@ +--- +title: "Build a REST API" +sidebarTitle: "REST API" +description: "Tutorial: Create a REST API with OpenHands" +--- + +# Tutorial: Build a REST API + +In this tutorial, you'll use OpenHands to build a complete REST API for a task management application. + +## Prerequisites + +- OpenHands CLI or Cloud access +- Python 3.10+ environment +- Basic understanding of REST APIs + +## What We'll Build + +A task management API with: +- CRUD operations for tasks +- User authentication +- Input validation +- Error handling + +## Step 1: Project Setup + +First, have OpenHands set up the project structure: + +```markdown +Create a new Python REST API project for task management. + +Structure: +``` +task-api/ +├── src/ +│ ├── __init__.py +│ ├── main.py # FastAPI application +│ ├── models/ # Pydantic models +│ ├── routes/ # API endpoints +│ └── services/ # Business logic +├── tests/ +├── requirements.txt +└── README.md +``` + +Use FastAPI with Pydantic for validation. +Include: uvicorn, pytest, httpx for testing. +``` + +## Step 2: Create the Task Model + +```markdown +Create the Task model and schemas. + +Location: src/models/task.py + +Fields: +- id: UUID (generated) +- title: string (required, max 100 chars) +- description: string (optional) +- status: enum (pending, in_progress, completed) +- created_at: datetime +- updated_at: datetime + +Create Pydantic schemas: +- TaskCreate (for POST) +- TaskUpdate (for PATCH) +- TaskResponse (for responses) +``` + +## Step 3: Implement CRUD Routes + +```markdown +Create CRUD endpoints for tasks. + +Location: src/routes/tasks.py + +Endpoints: +- GET /tasks - List all tasks (with pagination) +- GET /tasks/{id} - Get single task +- POST /tasks - Create task +- PATCH /tasks/{id} - Update task +- DELETE /tasks/{id} - Delete task + +Include: +- Input validation +- Proper HTTP status codes +- Error responses for not found, validation errors +``` + +## Step 4: Add Tests + +```markdown +Add comprehensive tests for the task API. + +Location: tests/test_tasks.py + +Test cases: +1. Create task - success +2. Create task - validation error (missing title) +3. Get task - success +4. Get task - not found +5. Update task - success +6. Delete task - success +7. List tasks - pagination + +Use pytest with httpx TestClient. +``` + +## Step 5: Documentation + +```markdown +Add API documentation. + +OpenAPI docs should include: +- Descriptions for all endpoints +- Request/response examples +- Error response schemas + +Create README with: +- Setup instructions +- API endpoint reference +- Example requests +``` + +## Running the API + +After OpenHands completes the implementation: + +```bash +# Install dependencies +pip install -r requirements.txt + +# Run the server +uvicorn src.main:app --reload + +# Run tests +pytest tests/ -v +``` + +## Expected Outcome + +You should have a working API: + +```bash +# Create a task +curl -X POST http://localhost:8000/tasks \ + -H "Content-Type: application/json" \ + -d '{"title": "Learn OpenHands", "status": "in_progress"}' + +# Response +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "title": "Learn OpenHands", + "description": null, + "status": "in_progress", + "created_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-01-15T10:30:00Z" +} +``` + +## Next Steps + +Extend this API by asking OpenHands to: + +- Add user authentication +- Add database persistence (SQLite/PostgreSQL) +- Add rate limiting +- Deploy to cloud platform + + + Explore other tutorials + diff --git a/use-cases/tutorials/test-coverage.mdx b/use-cases/tutorials/test-coverage.mdx new file mode 100644 index 00000000..ae89e304 --- /dev/null +++ b/use-cases/tutorials/test-coverage.mdx @@ -0,0 +1,205 @@ +--- +title: "Add Test Coverage" +sidebarTitle: "Test Coverage" +description: "Tutorial: Improve test coverage with OpenHands" +--- + +# Tutorial: Add Test Coverage + +Learn how to systematically add tests to an existing codebase using OpenHands. + +## Prerequisites + +- Existing codebase with limited test coverage +- Testing framework installed (pytest, jest, etc.) +- OpenHands CLI or Cloud access + +## Overview + +We'll follow this process: + + + + Identify untested code + + + Rank by criticality + + + Use OpenHands to write tests + + + Run and review tests + + + +## Step 1: Check Current Coverage + +First, measure existing coverage: + +```bash +# Python +pytest --cov=src --cov-report=html + +# JavaScript +npm test -- --coverage +``` + +## Step 2: Identify Critical Untested Code + +Ask OpenHands to analyze: + +```markdown +Analyze the codebase and identify critical untested functions. + +Focus on: +1. Business logic in src/services/ +2. Data validation in src/utils/ +3. API handlers in src/api/ + +List functions with: +- Function name and location +- Why it's critical +- Suggested test cases +``` + +## Step 3: Generate Tests Systematically + +### Module by Module + +For each module, provide a clear instruction: + +```markdown +Add tests for src/services/order_service.py + +Current coverage: 45% +Target coverage: 90% + +Functions to test: +1. create_order() +2. calculate_total() +3. apply_discount() +4. validate_order() + +Testing patterns: +- Follow existing tests in tests/services/test_user_service.py +- Use fixtures from conftest.py +- Mock external dependencies (PaymentGateway, InventoryService) + +For each function, test: +- Happy path +- Edge cases +- Error conditions +``` + +### Example Output + +```python +# tests/services/test_order_service.py +import pytest +from unittest.mock import Mock, patch +from src.services.order_service import OrderService + + +class TestCreateOrder: + @pytest.fixture + def order_service(self): + return OrderService() + + @pytest.fixture + def valid_order_data(self): + return { + "user_id": 1, + "items": [{"product_id": 1, "quantity": 2}], + "shipping_address": {"city": "NYC", "zip": "10001"} + } + + def test_create_order_success(self, order_service, valid_order_data): + order = order_service.create_order(valid_order_data) + assert order.status == "pending" + assert order.user_id == 1 + assert len(order.items) == 1 + + def test_create_order_empty_items(self, order_service): + with pytest.raises(ValueError, match="Order must have items"): + order_service.create_order({"user_id": 1, "items": []}) + + @patch('src.services.order_service.InventoryService') + def test_create_order_out_of_stock(self, mock_inventory, order_service): + mock_inventory.check_stock.return_value = False + with pytest.raises(OutOfStockError): + order_service.create_order({"user_id": 1, "items": [...]}) +``` + +## Step 4: Iterate and Refine + +After initial tests: + +```markdown +Review the test results and improve coverage. + +Current status: +- 15 tests added +- 3 tests failing +- Coverage at 78% (target: 90%) + +Fix the failing tests and add tests for: +- Edge case: order with more than 100 items +- Edge case: discount code expiration +- Integration: full order workflow +``` + +## Coverage Strategies + +### By Layer + +``` +Week 1: Service layer (business logic) +Week 2: API layer (endpoints) +Week 3: Utils (helpers, validators) +Week 4: Integration tests +``` + +### By Criticality + +1. Payment processing +2. Authentication +3. Order management +4. User management +5. Reporting + +## Best Practices + + + + Test what code does, not how + + + Test names should describe scenarios + + + Each test should run in isolation + + + Unit tests should be quick + + + +## Tracking Progress + +Monitor coverage improvement: + +```bash +# Generate coverage report +pytest --cov=src --cov-report=term-missing + +# Track over time +# Day 1: 45% +# Day 3: 65% +# Day 5: 85% +# Day 7: 92% +``` + + + More patterns for test generation + From f4c3e251426f7239743b9750b3898b99ab49b2b5 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 22 Jan 2026 14:58:13 +0000 Subject: [PATCH 2/5] fix: Update navigation structure based on feedback Changes: - Rename 'API Reference' tab back to 'SDK' (exact copy of original structure) - Move 'Best Practices' section from Documentation to Getting Started - Create new 'OpenHands Cloud' tab with: - Cloud getting started pages (openhands-cloud, cloud-ui, cloud-api, cli/cloud) - Cloud integrations (GitHub, GitLab, Bitbucket, Slack, Project Management) - REST API (openapi/openapi.json) - Remove Cloud-related content from Documentation tab - Simplify Integrations in Documentation to just overview and MCP servers Co-authored-by: openhands --- docs.json | 130 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 72 insertions(+), 58 deletions(-) diff --git a/docs.json b/docs.json index 4c747a1e..17a71b8d 100644 --- a/docs.json +++ b/docs.json @@ -31,6 +31,15 @@ "overview/faqs" ] }, + { + "group": "Best Practices", + "pages": [ + "openhands/usage/tips/prompting-best-practices", + "openhands/usage/tips/when-to-use-openhands", + "openhands/usage/tips/effective-instructions", + "openhands/usage/tips/good-vs-bad-instructions" + ] + }, { "group": "Community", "pages": [ @@ -46,7 +55,6 @@ { "group": "Setup & Installation", "pages": [ - "openhands/usage/cloud/openhands-cloud", "openhands/usage/cli/installation", "openhands/usage/run-openhands/local-setup", "openhands/usage/advanced/configuration-options" @@ -75,17 +83,6 @@ "group": "Integrations", "pages": [ "openhands/usage/integrations/overview", - "openhands/usage/cloud/github-installation", - "openhands/usage/cloud/gitlab-installation", - "openhands/usage/cloud/bitbucket-installation", - "openhands/usage/cloud/slack-installation", - { - "group": "Project Management", - "pages": [ - "openhands/usage/cloud/project-management/jira-integration", - "openhands/usage/cloud/project-management/linear-integration" - ] - }, "openhands/usage/cli/mcp-servers" ] }, @@ -170,35 +167,52 @@ ] }, { - "group": "Best Practices", + "group": "Reference", "pages": [ - "openhands/usage/tips/prompting-best-practices", - "openhands/usage/tips/when-to-use-openhands", - "openhands/usage/tips/effective-instructions", - "openhands/usage/tips/good-vs-bad-instructions" + "openhands/usage/cli/command-reference", + "openhands/usage/cli/resume" ] }, { - "group": "Cloud Features", + "group": "Help", + "pages": [ + "openhands/usage/troubleshooting/troubleshooting", + "openhands/usage/troubleshooting/feedback" + ] + } + ] + }, + { + "tab": "OpenHands Cloud", + "pages": [ + { + "group": "Getting Started", "pages": [ + "openhands/usage/cloud/openhands-cloud", "openhands/usage/cloud/cloud-ui", "openhands/usage/cloud/cloud-api", "openhands/usage/cli/cloud" ] }, { - "group": "Reference", + "group": "Integrations", "pages": [ - "openhands/usage/cli/command-reference", - "openhands/usage/cli/resume" + "openhands/usage/cloud/github-installation", + "openhands/usage/cloud/gitlab-installation", + "openhands/usage/cloud/bitbucket-installation", + "openhands/usage/cloud/slack-installation", + { + "group": "Project Management", + "pages": [ + "openhands/usage/cloud/project-management/jira-integration", + "openhands/usage/cloud/project-management/linear-integration" + ] + } ] }, { - "group": "Help", - "pages": [ - "openhands/usage/troubleshooting/troubleshooting", - "openhands/usage/troubleshooting/feedback" - ] + "group": "REST API", + "openapi": "openapi/openapi.json" } ] }, @@ -244,7 +258,7 @@ ] }, { - "tab": "API Reference", + "tab": "SDK", "pages": [ "sdk/index", "sdk/getting-started", @@ -265,41 +279,41 @@ "sdk/guides/metrics", "sdk/guides/observability", "sdk/guides/secrets", - "sdk/guides/hooks", - "sdk/guides/critic", { - "group": "Agent Configurations", + "group": "LLM Features", "pages": [ - "sdk/guides/agent-custom", + "sdk/guides/llm-registry", + "sdk/guides/llm-routing", + "sdk/guides/llm-reasoning", + "sdk/guides/llm-streaming", + "sdk/guides/llm-image-input", + "sdk/guides/llm-error-handling" + ] + }, + { + "group": "Agent Features", + "pages": [ + "sdk/guides/agent-interactive-terminal", "sdk/guides/agent-browser-use", + "sdk/guides/agent-custom", + "sdk/guides/convo-custom-visualizer", + "sdk/guides/agent-stuck-detector", "sdk/guides/agent-tom-agent", - "sdk/guides/agent-interactive-terminal", - "sdk/guides/agent-stuck-detector" + "sdk/guides/critic" ] }, { - "group": "Conversation Management", + "group": "Conversation Features", "pages": [ - "sdk/guides/convo-async", "sdk/guides/convo-pause-and-resume", "sdk/guides/convo-send-message-while-running", + "sdk/guides/convo-async", "sdk/guides/convo-ask-agent", - "sdk/guides/convo-custom-visualizer" - ] - }, - { - "group": "LLM Configuration", - "pages": [ - "sdk/guides/llm-registry", - "sdk/guides/llm-routing", - "sdk/guides/llm-streaming", - "sdk/guides/llm-reasoning", - "sdk/guides/llm-image-input", - "sdk/guides/llm-error-handling" + "sdk/guides/hooks" ] }, { - "group": "Agent Server", + "group": "Remote Agent Server", "pages": [ "sdk/guides/agent-server/overview", "sdk/guides/agent-server/local-server", @@ -307,7 +321,14 @@ "sdk/guides/agent-server/apptainer-sandbox", "sdk/guides/agent-server/api-sandbox", "sdk/guides/agent-server/cloud-workspace", - "sdk/guides/agent-server/custom-tools" + "sdk/guides/agent-server/custom-tools", + { + "group": "API Reference", + "openapi": { + "source": "/openapi/agent-sdk.json", + "directory": "sdk/guides/agent-server/api-reference" + } + } ] }, { @@ -325,18 +346,15 @@ "pages": [ "sdk/arch/overview", "sdk/arch/design", - "sdk/arch/sdk", { - "group": "Components", + "group": "SDK Components", "pages": [ "sdk/arch/agent", - "sdk/arch/agent-server", "sdk/arch/conversation", "sdk/arch/tool-system", "sdk/arch/events", "sdk/arch/workspace", "sdk/arch/llm", - "sdk/arch/mcp", "sdk/arch/skill", "sdk/arch/condenser", "sdk/arch/security" @@ -345,7 +363,7 @@ ] }, { - "group": "Python API Reference", + "group": "API Reference", "pages": [ "sdk/api-reference/openhands.sdk.agent", "sdk/api-reference/openhands.sdk.conversation", @@ -356,10 +374,6 @@ "sdk/api-reference/openhands.sdk.utils", "sdk/api-reference/openhands.sdk.workspace" ] - }, - { - "group": "REST API", - "openapi": "openapi/openapi.json" } ] } From 1290bd500113b1bd12d8339dea8c538e5fdb3a0b Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 22 Jan 2026 16:50:46 +0000 Subject: [PATCH 3/5] fix: Remove SDK redirect causing infinite loop The redirect from /sdk to /sdk/index was conflicting with the tab navigation, causing too many redirects error when clicking on SDK tab. Co-authored-by: openhands --- docs.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs.json b/docs.json index 17a71b8d..5ea54d06 100644 --- a/docs.json +++ b/docs.json @@ -603,10 +603,6 @@ { "source": "/openhands/usage/run-openhands/cli/resume", "destination": "/openhands/usage/cli/resume" - }, - { - "source": "/sdk", - "destination": "/sdk/index" } ] } From 7fd371db85755b367ec462e719775c7380069b5e Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 22 Jan 2026 17:28:07 +0000 Subject: [PATCH 4/5] docs: Add detailed gap analysis comparing Devin documentation Added comprehensive gap analysis to docs-navigation-proposal.md: ## HIGH PRIORITY Gaps (Critical for user success): - Your First Session - step-by-step guide for first interaction - SDLC Integration - how OpenHands fits into dev workflows - Workspace & Session Tools - understanding IDE, Browser, Shell - Repository Setup Guide - comprehensive repo configuration ## MEDIUM PRIORITY Gaps: - Limitations & Best Fit Tasks - Playbooks / Reusable Prompts - Slash Commands (if applicable) - Ask Mode / Q&A Mode - Session Insights / Analytics ## LOWER PRIORITY Gaps: - Advanced Mode / Batch Sessions - Deployments - PR Templates - Security Practices - Common Issues Also documented which pages were already created in this PR. Co-authored-by: openhands --- docs-navigation-proposal.md | 518 ++++++++++++++++++++++++++++++++++++ 1 file changed, 518 insertions(+) create mode 100644 docs-navigation-proposal.md diff --git a/docs-navigation-proposal.md b/docs-navigation-proposal.md new file mode 100644 index 00000000..08607d04 --- /dev/null +++ b/docs-navigation-proposal.md @@ -0,0 +1,518 @@ +# OpenHands Documentation Navigation Restructure Proposal + +## Executive Summary + +This document proposes a restructured navigation for OpenHands documentation that aligns with Devin.ai's documentation structure. The key changes include: + +1. **Merging CLI and Web tabs** into a single "Documentation" section +2. **Creating a new "Use Cases" tab** for tutorials and examples +3. **Reorganizing content** into logical groupings similar to Devin's approach +4. **Identifying gaps** that should be filled with new pages + +--- + +## Current Structure Comparison + +### Devin.ai Documentation Tabs +| Tab | Description | +|-----|-------------| +| **Documentation** | Main product documentation (Get Started, Guidelines, Onboarding, Working with Devin, Product Guides, Integrations, Admin) | +| **Use Cases & Tutorials** | Examples, use cases, prompts, tutorials | +| **API Reference** | REST API documentation with versions | +| **Release Notes** | Product changelog | +| **Enterprise** | Enterprise-specific features | + +### OpenHands Current Tabs +| Tab | Description | +|-----|-------------| +| **Overview** | Introduction, quick start, FAQs, community | +| **Web** | Cloud, Local GUI, REST API, settings, advanced config | +| **CLI** | Installation, ways to run, cloud, extensions | +| **SDK** | Python SDK documentation | + +--- + +## Proposed New Navigation Structure + +### Tab 1: Getting Started +*Mirrors Devin's "Get Started" section within Documentation* + +``` +Getting Started +├── Introduction +├── Quick Start +├── First Projects +├── FAQs +├── Community +└── Contributing +``` + +### Tab 2: Documentation +*Merged CLI + Web with unified content* + +``` +Documentation +├── Setup & Installation +│ ├── OpenHands Cloud [EXISTING: openhands/usage/cloud/openhands-cloud] +│ ├── Local Installation (CLI) [EXISTING: openhands/usage/cli/installation] +│ ├── Local GUI Setup [EXISTING: openhands/usage/run-openhands/local-setup] +│ └── Configuration Options [EXISTING: openhands/usage/advanced/configuration-options] +│ +├── Running OpenHands +│ ├── Terminal (TUI) [EXISTING: openhands/usage/cli/terminal] +│ ├── Web Interface [EXISTING: openhands/usage/cli/web-interface] +│ ├── Headless Mode [EXISTING: openhands/usage/cli/headless] +│ ├── GUI Server [EXISTING: openhands/usage/cli/gui-server] +│ └── IDE Integration (ACP) +│ ├── Overview [EXISTING: openhands/usage/cli/ide/overview] +│ ├── VS Code [EXISTING: openhands/usage/cli/ide/vscode] +│ ├── JetBrains [EXISTING: openhands/usage/cli/ide/jetbrains] +│ ├── Zed [EXISTING: openhands/usage/cli/ide/zed] +│ └── Toad [EXISTING: openhands/usage/cli/ide/toad] +│ +├── Integrations [Mirrors Devin's Integrations section] +│ ├── Integrations Overview [GAP: NEW PAGE NEEDED] +│ ├── GitHub [EXISTING: openhands/usage/cloud/github-installation] +│ ├── GitLab [EXISTING: openhands/usage/cloud/gitlab-installation] +│ ├── Bitbucket [EXISTING: openhands/usage/cloud/bitbucket-installation] +│ ├── Slack [EXISTING: openhands/usage/cloud/slack-installation] +│ ├── Project Management +│ │ ├── Jira [EXISTING: openhands/usage/cloud/project-management/jira-integration] +│ │ └── Linear [EXISTING: openhands/usage/cloud/project-management/linear-integration] +│ └── MCP Servers [EXISTING: openhands/usage/cli/mcp-servers] +│ +├── Features & Configuration +│ ├── Key Features [EXISTING: openhands/usage/key-features] +│ ├── Skills (Microagents) +│ │ ├── Overview [EXISTING: overview/skills] +│ │ ├── Repository Skills [EXISTING: overview/skills/repo] +│ │ ├── Keyword Skills [EXISTING: overview/skills/keyword] +│ │ ├── Organization Skills [EXISTING: overview/skills/org] +│ │ └── Public Skills [EXISTING: overview/skills/public] +│ ├── Model Context Protocol (MCP) [EXISTING: overview/model-context-protocol] +│ ├── Repository Customization [EXISTING: openhands/usage/customization/repository] +│ └── Critic Extension [EXISTING: openhands/usage/cli/critic] +│ +├── Settings [Unified settings section] +│ ├── Application Settings [EXISTING: openhands/usage/settings/application-settings] +│ ├── LLM Settings [EXISTING: openhands/usage/settings/llm-settings] +│ ├── Integrations Settings [EXISTING: openhands/usage/settings/integrations-settings] +│ ├── Secrets Settings [EXISTING: openhands/usage/settings/secrets-settings] +│ ├── API Keys Settings [EXISTING: openhands/usage/settings/api-keys-settings] +│ └── MCP Settings [EXISTING: openhands/usage/settings/mcp-settings] +│ +├── Advanced Configuration +│ ├── LLM Configuration +│ │ ├── Overview [EXISTING: openhands/usage/llms/llms] +│ │ └── Providers +│ │ ├── OpenHands LLMs [EXISTING: openhands/usage/llms/openhands-llms] +│ │ ├── Azure [EXISTING: openhands/usage/llms/azure-llms] +│ │ ├── Google [EXISTING: openhands/usage/llms/google-llms] +│ │ ├── Groq [EXISTING: openhands/usage/llms/groq] +│ │ ├── Local LLMs [EXISTING: openhands/usage/llms/local-llms] +│ │ ├── LiteLLM Proxy [EXISTING: openhands/usage/llms/litellm-proxy] +│ │ ├── Moonshot [EXISTING: openhands/usage/llms/moonshot] +│ │ ├── OpenAI [EXISTING: openhands/usage/llms/openai-llms] +│ │ └── OpenRouter [EXISTING: openhands/usage/llms/openrouter] +│ ├── Runtime Configuration +│ │ ├── Overview [EXISTING: openhands/usage/runtimes/overview] +│ │ └── Providers +│ │ ├── Docker [EXISTING: openhands/usage/runtimes/docker] +│ │ ├── Remote [EXISTING: openhands/usage/runtimes/remote] +│ │ ├── Local [EXISTING: openhands/usage/runtimes/local] +│ │ └── Third-Party +│ │ ├── Modal [EXISTING: openhands/usage/runtimes/modal] +│ │ ├── Daytona [EXISTING: openhands/usage/runtimes/daytona] +│ │ ├── Runloop [EXISTING: openhands/usage/runtimes/runloop] +│ │ └── E2B [EXISTING: openhands/usage/runtimes/e2b] +│ ├── Custom Sandbox [EXISTING: openhands/usage/advanced/custom-sandbox-guide] +│ └── Search Engine Setup [EXISTING: openhands/usage/advanced/search-engine-setup] +│ +├── Best Practices [Mirrors Devin's Essential Guidelines] +│ ├── Prompting Best Practices [EXISTING: openhands/usage/tips/prompting-best-practices] +│ ├── When to Use OpenHands [GAP: NEW PAGE NEEDED - mirrors Devin's "When to Use Devin"] +│ ├── Writing Effective Instructions [GAP: NEW PAGE NEEDED - mirrors "Instructing Devin Effectively"] +│ └── Good vs Bad Instructions [GAP: NEW PAGE NEEDED - mirrors Devin's examples] +│ +├── Cloud Features [Cloud-specific features] +│ ├── Cloud UI [EXISTING: openhands/usage/cloud/cloud-ui] +│ ├── Cloud API [EXISTING: openhands/usage/cloud/cloud-api] +│ └── CLI Cloud Mode [EXISTING: openhands/usage/cli/cloud] +│ +├── Reference +│ ├── Command Reference [EXISTING: openhands/usage/cli/command-reference] +│ └── Resume Conversations [EXISTING: openhands/usage/cli/resume] +│ +└── Help + ├── Troubleshooting [EXISTING: openhands/usage/troubleshooting/troubleshooting] + └── Feedback [EXISTING: openhands/usage/troubleshooting/feedback] +``` + +### Tab 3: Use Cases +*NEW TAB - Mirrors Devin's "Use Cases & Tutorials"* + +``` +Use Cases +├── Overview [GAP: NEW PAGE NEEDED] +├── Best Practices [GAP: NEW PAGE NEEDED] +│ +├── Use Cases [GAP: NEW SECTION NEEDED] +│ ├── Code Migrations [GAP: NEW PAGE NEEDED] +│ ├── Test Coverage Improvement [GAP: NEW PAGE NEEDED] +│ ├── Bug Fixing & Debugging [GAP: NEW PAGE NEEDED] +│ ├── Documentation Generation [GAP: NEW PAGE NEEDED] +│ ├── Code Refactoring [GAP: NEW PAGE NEEDED] +│ └── API Integration [GAP: NEW PAGE NEEDED] +│ +├── Tutorials +│ ├── First Projects [EXISTING: overview/first-projects - move here] +│ ├── Building a REST API [GAP: NEW PAGE NEEDED] +│ ├── Adding Test Coverage [GAP: NEW PAGE NEEDED] +│ ├── Containerizing Applications [GAP: NEW PAGE NEEDED] +│ └── Frontend Development [GAP: NEW PAGE NEEDED] +│ +└── Prompt Library [GAP: NEW SECTION NEEDED] + ├── Testing & Refactoring [GAP: NEW PAGE NEEDED] + ├── Data & Analysis [GAP: NEW PAGE NEEDED] + └── Web Development [GAP: NEW PAGE NEEDED] +``` + +### Tab 4: SDK / API Reference +*Enhanced SDK section with REST API integrated* + +``` +SDK / API Reference +├── Software Agent SDK [EXISTING: sdk/index] +├── Getting Started [EXISTING: sdk/getting-started] +├── FAQ [EXISTING: sdk/faq] +│ +├── Guides +│ ├── Hello World [EXISTING: sdk/guides/hello-world] +│ ├── Custom Tools [EXISTING: sdk/guides/custom-tools] +│ ├── MCP Integration [EXISTING: sdk/guides/mcp] +│ ├── Skills & Context [EXISTING: sdk/guides/skill] +│ ├── Plugins [EXISTING: sdk/guides/plugins] +│ ├── Persistence [EXISTING: sdk/guides/convo-persistence] +│ ├── Context Condenser [EXISTING: sdk/guides/context-condenser] +│ ├── Sub-Agent Delegation [EXISTING: sdk/guides/agent-delegation] +│ ├── Iterative Refinement [EXISTING: sdk/guides/iterative-refinement] +│ ├── Security & Action Confirmation [EXISTING: sdk/guides/security] +│ ├── Metrics Tracking [EXISTING: sdk/guides/metrics] +│ ├── Observability & Tracing [EXISTING: sdk/guides/observability] +│ ├── Secret Registry [EXISTING: sdk/guides/secrets] +│ ├── Hooks [EXISTING: sdk/guides/hooks] +│ ├── Critic [EXISTING: sdk/guides/critic] +│ ├── Agent Configurations +│ │ ├── Custom Agent [EXISTING: sdk/guides/agent-custom] +│ │ ├── Browser Use [EXISTING: sdk/guides/agent-browser-use] +│ │ ├── ToM Agent [EXISTING: sdk/guides/agent-tom-agent] +│ │ ├── Interactive Terminal [EXISTING: sdk/guides/agent-interactive-terminal] +│ │ └── Stuck Detector [EXISTING: sdk/guides/agent-stuck-detector] +│ ├── Conversation Management +│ │ ├── Async Conversations [EXISTING: sdk/guides/convo-async] +│ │ ├── Pause and Resume [EXISTING: sdk/guides/convo-pause-and-resume] +│ │ ├── Send Message While Running [EXISTING: sdk/guides/convo-send-message-while-running] +│ │ ├── Ask Agent [EXISTING: sdk/guides/convo-ask-agent] +│ │ └── Custom Visualizer [EXISTING: sdk/guides/convo-custom-visualizer] +│ ├── LLM Configuration +│ │ ├── Registry [EXISTING: sdk/guides/llm-registry] +│ │ ├── Routing [EXISTING: sdk/guides/llm-routing] +│ │ ├── Streaming [EXISTING: sdk/guides/llm-streaming] +│ │ ├── Reasoning [EXISTING: sdk/guides/llm-reasoning] +│ │ ├── Image Input [EXISTING: sdk/guides/llm-image-input] +│ │ └── Error Handling [EXISTING: sdk/guides/llm-error-handling] +│ ├── Agent Server +│ │ ├── Overview [EXISTING: sdk/guides/agent-server/overview] +│ │ ├── Local Server [EXISTING: sdk/guides/agent-server/local-server] +│ │ ├── Docker Sandbox [EXISTING: sdk/guides/agent-server/docker-sandbox] +│ │ ├── Apptainer Sandbox [EXISTING: sdk/guides/agent-server/apptainer-sandbox] +│ │ ├── API Sandbox [EXISTING: sdk/guides/agent-server/api-sandbox] +│ │ ├── Cloud Workspace [EXISTING: sdk/guides/agent-server/cloud-workspace] +│ │ └── Custom Tools [EXISTING: sdk/guides/agent-server/custom-tools] +│ └── GitHub Workflows +│ ├── PR Review [EXISTING: sdk/guides/github-workflows/pr-review] +│ ├── TODO Management [EXISTING: sdk/guides/github-workflows/todo-management] +│ └── Assign Reviews [EXISTING: sdk/guides/github-workflows/assign-reviews] +│ +├── Architecture +│ ├── Overview [EXISTING: sdk/arch/overview] +│ ├── Design Principles [EXISTING: sdk/arch/design] +│ ├── SDK Overview [EXISTING: sdk/arch/sdk] +│ └── Components +│ ├── Agent [EXISTING: sdk/arch/agent] +│ ├── Agent Server [EXISTING: sdk/arch/agent-server] +│ ├── Conversation [EXISTING: sdk/arch/conversation] +│ ├── Tool System [EXISTING: sdk/arch/tool-system] +│ ├── Events [EXISTING: sdk/arch/events] +│ ├── Workspace [EXISTING: sdk/arch/workspace] +│ ├── LLM [EXISTING: sdk/arch/llm] +│ ├── MCP [EXISTING: sdk/arch/mcp] +│ ├── Skill [EXISTING: sdk/arch/skill] +│ ├── Condenser [EXISTING: sdk/arch/condenser] +│ └── Security [EXISTING: sdk/arch/security] +│ +├── Python API Reference +│ ├── openhands.sdk.agent [EXISTING: sdk/api-reference/openhands.sdk.agent] +│ ├── openhands.sdk.conversation [EXISTING: sdk/api-reference/openhands.sdk.conversation] +│ ├── openhands.sdk.event [EXISTING: sdk/api-reference/openhands.sdk.event] +│ ├── openhands.sdk.llm [EXISTING: sdk/api-reference/openhands.sdk.llm] +│ ├── openhands.sdk.security [EXISTING: sdk/api-reference/openhands.sdk.security] +│ ├── openhands.sdk.tool [EXISTING: sdk/api-reference/openhands.sdk.tool] +│ ├── openhands.sdk.utils [EXISTING: sdk/api-reference/openhands.sdk.utils] +│ └── openhands.sdk.workspace [EXISTING: sdk/api-reference/openhands.sdk.workspace] +│ +└── REST API [Moved from Web tab] + └── OpenAPI Reference [EXISTING: openapi/openapi.json] +``` + +--- + +## Gap Analysis + +### Devin Documentation Structure Overview + +Devin's Documentation section is organized into these key areas: + +| Section | Purpose | +|---------|---------| +| **Get Started** | Introduction, First Session, Tutorial Library | +| **Essential Guidelines** | When to use, Effective instructions, Good vs bad examples, SDLC integration | +| **Onboarding** | Repo setup, Indexing, VPN, Knowledge onboarding, AGENTS.md | +| **Working with Agent** | Session tools, Slash commands, Ask mode, Advanced mode | +| **Product Guides** | Knowledge, Session insights, Secrets, Playbooks, Deployments, Team management | +| **Integrations** | All platform integrations (GitHub, Slack, Jira, etc.) | +| **Admin** | Security, Billing, Common issues | + +--- + +### 🔴 HIGH PRIORITY Gaps - Core Onboarding & Workflow + +These pages are **critical** for user success and enterprise adoption: + +| Missing Page | Devin Equivalent | Why It's Critical | +|--------------|------------------|-------------------| +| **Your First Session** | `/get-started/first-run` | Step-by-step guide for starting first session, understanding interface, @ mentions, slash commands. Currently only partially covered in `quickstart.mdx`. | +| **SDLC Integration** | `/essential-guidelines/sdlc-integration` | How OpenHands fits into existing dev workflows (planning → dev → test → review → deploy). **Critical for enterprise adoption.** | +| **Workspace & Session Tools** | `/work-with-devin/devin-session-tools` | Understanding IDE, Browser, Shell tools during sessions; how to take over tasks, monitor progress. **Users need this to understand the workspace.** | +| **Repository Setup Guide** | `/onboard-devin/repo-setup` | Comprehensive guide for setting up lint commands, test commands, dependencies, environment variables. Current `repository.mdx` is incomplete. | + +#### Recommended New Pages (HIGH Priority) + +**1. Your First Session** (`overview/your-first-session.mdx`) +``` +Content: +- Understanding the OpenHands interface (Chat, Terminal, Browser, Code Editor) +- Starting your first task +- Monitoring agent progress +- Taking over from the agent +- Common first-task examples with sample prompts +- Tips for successful first sessions +``` + +**2. SDLC Integration** (`openhands/usage/sdlc-integration.mdx`) +``` +Content: +- Overview: Where OpenHands fits in your development workflow +- Planning phase: Codebase exploration, task scoping +- Development phase: Delegating tasks, parallel execution +- Testing phase: Running tests, generating test coverage +- Code review: PR creation and automated review +- Deployment: CI/CD integration +- Best practices for team integration +``` + +**3. Workspace & Session Tools** (`openhands/usage/workspace-tools.mdx`) +``` +Content: +- Understanding the OpenHands workspace +- Terminal/Shell usage and monitoring +- Code editor integration +- Browser tool for web testing +- Progress tracking and session timeline +- Taking over a session +- Running your own commands +- Best practices for collaboration +``` + +**4. Repository Setup Guide** (`openhands/usage/repo-setup.mdx` - enhance existing) +``` +Content: +- Setting up test commands +- Setting up lint commands +- Configuring environment variables +- Dependencies management +- Custom setup scripts +- Per-repo configuration +- Troubleshooting common setup issues +``` + +--- + +### 🟠 MEDIUM PRIORITY Gaps - Feature Documentation + +| Missing Page | Devin Equivalent | Description | +|--------------|------------------|-------------| +| **Playbooks / Reusable Prompts** | `/product-guides/creating-playbooks` | Reusable prompt templates for repeated tasks. Valuable for power users and teams. | +| **Slash Commands** | `/work-with-devin/slash-commands` | Built-in command shortcuts (/plan, /review, /test). If OpenHands supports similar, needs documentation. | +| **Ask Mode / Q&A Mode** | `/work-with-devin/ask-devin` | Lightweight mode for exploring codebase without making changes. Different interaction paradigm. | +| **Session Insights / Analytics** | `/product-guides/session-insights` | Analytics and debugging for sessions. Helpful for troubleshooting and improvement. | +| **Index a Repository** | `/onboard-devin/index-repo` | How the agent indexes and understands a codebase. Important for understanding capabilities. | +| **Limitations & Best Fit Tasks** | (from `/get-started/devin-intro`) | Clear documentation of current limitations and what tasks work best. | + +#### Recommended New Pages (MEDIUM Priority) + +**5. Limitations & Best Fit Tasks** (`openhands/usage/tips/limitations.mdx`) +``` +Content: +- What OpenHands excels at (list with examples) +- Current limitations (honest assessment) +- Tasks to avoid or break down +- How to scope tasks appropriately +- Task complexity guidelines +``` + +**6. Playbooks / Reusable Prompts** (`openhands/usage/playbooks.mdx`) +``` +Content: +- What are playbooks? +- Creating effective playbooks +- Sharing playbooks with your team +- Example playbooks for common tasks +- Best practices for playbook design +``` + +--- + +### 🟡 LOWER PRIORITY Gaps - Advanced Features + +| Missing Page | Devin Equivalent | Description | +|--------------|------------------|-------------| +| **Advanced Mode / Batch Sessions** | `/work-with-devin/advanced-mode` | Running multiple sessions in parallel | +| **Deployments** | `/product-guides/deployment-capabilities` | How to deploy code the agent creates | +| **PR Templates** | `/integrations/pr-templates` | Customizing PR format for agent-created PRs | +| **VPN Configuration** | `/onboard-devin/vpn` | Connecting to private networks | +| **Team Management** | `/product-guides/invite-team` | Team invitations and permissions (Cloud-specific) | +| **Security Practices** | `/admin/security` | Security practices and compliance documentation | +| **Billing & Usage** | `/admin/billing` | Pricing and usage information (Cloud-specific) | +| **Common Issues** | `/admin/common-issues` | FAQ-style troubleshooting for common problems | + +--- + +### Pages Already Created in This PR + +The following gap pages have already been created: + +| Page | Status | +|------|--------| +| ✅ Integrations Overview | `openhands/usage/integrations/overview.mdx` | +| ✅ When to Use OpenHands | `openhands/usage/tips/when-to-use-openhands.mdx` | +| ✅ Writing Effective Instructions | `openhands/usage/tips/effective-instructions.mdx` | +| ✅ Good vs Bad Instructions | `openhands/usage/tips/good-vs-bad-instructions.mdx` | +| ✅ Use Cases Overview | `use-cases/overview.mdx` | +| ✅ Use Cases Best Practices | `use-cases/best-practices.mdx` | +| ✅ Code Migrations Example | `use-cases/examples/code-migrations.mdx` | +| ✅ Test Coverage Example | `use-cases/examples/test-coverage.mdx` | +| ✅ Bug Fixing Example | `use-cases/examples/bug-fixing.mdx` | +| ✅ Documentation Example | `use-cases/examples/documentation.mdx` | +| ✅ Refactoring Example | `use-cases/examples/refactoring.mdx` | +| ✅ API Integration Example | `use-cases/examples/api-integration.mdx` | +| ✅ Tutorials (5 pages) | `use-cases/tutorials/*.mdx` | +| ✅ Prompt Library (3 pages) | `use-cases/prompts/*.mdx` | + +### Pages Still Needed (Prioritized) + +| Priority | Page | Recommended Path | +|----------|------|------------------| +| 🔴 HIGH | Your First Session | `overview/your-first-session.mdx` | +| 🔴 HIGH | SDLC Integration | `openhands/usage/sdlc-integration.mdx` | +| 🔴 HIGH | Workspace & Session Tools | `openhands/usage/workspace-tools.mdx` | +| 🔴 HIGH | Repository Setup Guide (enhanced) | `openhands/usage/repo-setup.mdx` | +| 🟠 MEDIUM | Limitations & Best Fit Tasks | `openhands/usage/tips/limitations.mdx` | +| 🟠 MEDIUM | Playbooks / Reusable Prompts | `openhands/usage/playbooks.mdx` | +| 🟡 LOW | Security Practices | `openhands/usage/admin/security.mdx` | +| 🟡 LOW | Common Issues | `openhands/usage/admin/common-issues.mdx` | + +--- + +## CLI/Web Merge Strategy + +### Features Available in Both CLI and Web +For these features, create a single unified page with platform-specific callouts: + +```markdown + +This feature is available in both the CLI and Web interface. + +``` + +**Unified Features:** +- MCP Configuration +- LLM Settings +- Secrets Management +- Repository Customization +- Headless Mode execution + +### CLI-Only Features +Add callout indicating CLI exclusivity: + +```markdown + +This feature is currently only available in the OpenHands CLI. + +``` + +**CLI-Only Features:** +- Terminal (TUI) mode +- IDE Integration (ACP) +- Command reference +- Resume conversations +- Critic extension + +### Web/Cloud-Only Features +Add callout indicating Web/Cloud exclusivity: + +```markdown + +This feature is only available in OpenHands Cloud or the Local GUI. + +``` + +**Web/Cloud-Only Features:** +- Cloud UI interface +- Cloud API +- Slack integration +- Project management integrations (Jira, Linear) +- GitHub/GitLab/Bitbucket deep integrations + +--- + +## Proposed docs.json Configuration + +See the `docs-navigation-new.json` file for the complete Mintlify configuration. + +--- + +## Implementation Notes + +### Phase 1: Restructure Navigation +1. Update `docs.json` with new tab structure +2. Move existing pages to new locations (using redirects) +3. Add platform availability callouts to merged pages + +### Phase 2: Fill High-Priority Gaps +1. Create Integrations Overview page +2. Create "When to Use OpenHands" page +3. Create "Writing Effective Instructions" page +4. Create "Good vs Bad Instructions" page +5. Create Use Cases Overview page + +### Phase 3: Add Use Cases Content +1. Create tutorial content based on existing "First Projects" +2. Add code migration examples +3. Add test coverage tutorial +4. Create prompt library section + +### Phase 4: Polish and Redirects +1. Set up redirects for moved pages +2. Update internal links +3. Test navigation flow From d2a19de2f0cce289b527456fb79007bffb211167 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 22 Jan 2026 19:34:00 +0000 Subject: [PATCH 5/5] Restructure docs navigation and add gap analysis pages Navigation changes: - Move Use Cases tab to right after Documentation - Rename GUI Server to Local GUI, position under Terminal (TUI) - Make Web Interface a sub-page of Terminal (TUI) - Move OpenHands Cloud page as sub-page of Terminal (TUI) - Add redirect from gui-server to local-gui New HIGH priority pages: - Your First Session: Step-by-step first interaction guide - SDLC Integration: How OpenHands fits in development lifecycle - Workspace & Session Tools: Understanding workspace and tools - Repository Setup Guide: Configuration for test/lint/build commands New MEDIUM priority pages: - Limitations & Best Fit Tasks: Capabilities and constraints - Playbooks & Reusable Prompts: Template prompts for common tasks Co-authored-by: openhands --- docs.json | 91 ++-- .../cli/{gui-server.mdx => local-gui.mdx} | 2 +- openhands/usage/cli/quick-start.mdx | 2 +- openhands/usage/cli/web-interface.mdx | 4 +- openhands/usage/playbooks.mdx | 398 ++++++++++++++++++ openhands/usage/repo-setup.mdx | 373 ++++++++++++++++ openhands/usage/sdlc-integration.mdx | 301 +++++++++++++ openhands/usage/tips/limitations.mdx | 281 +++++++++++++ openhands/usage/workspace-tools.mdx | 328 +++++++++++++++ overview/your-first-session.mdx | 202 +++++++++ 10 files changed, 1940 insertions(+), 42 deletions(-) rename openhands/usage/cli/{gui-server.mdx => local-gui.mdx} (99%) create mode 100644 openhands/usage/playbooks.mdx create mode 100644 openhands/usage/repo-setup.mdx create mode 100644 openhands/usage/sdlc-integration.mdx create mode 100644 openhands/usage/tips/limitations.mdx create mode 100644 openhands/usage/workspace-tools.mdx create mode 100644 overview/your-first-session.mdx diff --git a/docs.json b/docs.json index 5ea54d06..514c25d8 100644 --- a/docs.json +++ b/docs.json @@ -27,6 +27,7 @@ "pages": [ "overview/introduction", "overview/quickstart", + "overview/your-first-session", "overview/first-projects", "overview/faqs" ] @@ -37,7 +38,8 @@ "openhands/usage/tips/prompting-best-practices", "openhands/usage/tips/when-to-use-openhands", "openhands/usage/tips/effective-instructions", - "openhands/usage/tips/good-vs-bad-instructions" + "openhands/usage/tips/good-vs-bad-instructions", + "openhands/usage/tips/limitations" ] }, { @@ -63,10 +65,16 @@ { "group": "Running OpenHands", "pages": [ - "openhands/usage/cli/terminal", - "openhands/usage/cli/web-interface", + { + "group": "Terminal (TUI)", + "pages": [ + "openhands/usage/cli/terminal", + "openhands/usage/cli/web-interface", + "openhands/usage/cloud/openhands-cloud" + ] + }, + "openhands/usage/cli/local-gui", "openhands/usage/cli/headless", - "openhands/usage/cli/gui-server", { "group": "IDE Integration (ACP)", "pages": [ @@ -90,6 +98,10 @@ "group": "Features & Configuration", "pages": [ "openhands/usage/key-features", + "openhands/usage/workspace-tools", + "openhands/usage/sdlc-integration", + "openhands/usage/repo-setup", + "openhands/usage/playbooks", { "group": "Skills", "pages": [ @@ -182,40 +194,6 @@ } ] }, - { - "tab": "OpenHands Cloud", - "pages": [ - { - "group": "Getting Started", - "pages": [ - "openhands/usage/cloud/openhands-cloud", - "openhands/usage/cloud/cloud-ui", - "openhands/usage/cloud/cloud-api", - "openhands/usage/cli/cloud" - ] - }, - { - "group": "Integrations", - "pages": [ - "openhands/usage/cloud/github-installation", - "openhands/usage/cloud/gitlab-installation", - "openhands/usage/cloud/bitbucket-installation", - "openhands/usage/cloud/slack-installation", - { - "group": "Project Management", - "pages": [ - "openhands/usage/cloud/project-management/jira-integration", - "openhands/usage/cloud/project-management/linear-integration" - ] - } - ] - }, - { - "group": "REST API", - "openapi": "openapi/openapi.json" - } - ] - }, { "tab": "Use Cases", "pages": [ @@ -257,6 +235,39 @@ } ] }, + { + "tab": "OpenHands Cloud", + "pages": [ + { + "group": "Getting Started", + "pages": [ + "openhands/usage/cloud/cloud-ui", + "openhands/usage/cloud/cloud-api", + "openhands/usage/cli/cloud" + ] + }, + { + "group": "Integrations", + "pages": [ + "openhands/usage/cloud/github-installation", + "openhands/usage/cloud/gitlab-installation", + "openhands/usage/cloud/bitbucket-installation", + "openhands/usage/cloud/slack-installation", + { + "group": "Project Management", + "pages": [ + "openhands/usage/cloud/project-management/jira-integration", + "openhands/usage/cloud/project-management/linear-integration" + ] + } + ] + }, + { + "group": "REST API", + "openapi": "openapi/openapi.json" + } + ] + }, { "tab": "SDK", "pages": [ @@ -440,6 +451,10 @@ "source": "/usage/:slug*", "destination": "/openhands/usage/:slug*" }, + { + "source": "/openhands/usage/cli/gui-server", + "destination": "/openhands/usage/cli/local-gui" + }, { "source": "/openhands/usage/configuration-options", "destination": "/openhands/usage/advanced/configuration-options" diff --git a/openhands/usage/cli/gui-server.mdx b/openhands/usage/cli/local-gui.mdx similarity index 99% rename from openhands/usage/cli/gui-server.mdx rename to openhands/usage/cli/local-gui.mdx index cbbeebb1..5233c9c0 100644 --- a/openhands/usage/cli/gui-server.mdx +++ b/openhands/usage/cli/local-gui.mdx @@ -1,5 +1,5 @@ --- -title: GUI Server +title: Local GUI description: Launch the full OpenHands web GUI using Docker --- diff --git a/openhands/usage/cli/quick-start.mdx b/openhands/usage/cli/quick-start.mdx index d0fe1dde..86030beb 100644 --- a/openhands/usage/cli/quick-start.mdx +++ b/openhands/usage/cli/quick-start.mdx @@ -12,7 +12,7 @@ The OpenHands CLI provides multiple ways to interact with the OpenHands AI agent | [Terminal (TUI)](/openhands/usage/cli/terminal) | `openhands` | Interactive development | | [Headless](/openhands/usage/cli/headless) | `openhands --headless` | Scripts & automation | | [Web Interface](/openhands/usage/cli/web-interface) | `openhands web` | Browser-based TUI | -| [GUI Server](/openhands/usage/cli/gui-server) | `openhands serve` | Full web GUI | +| [Local GUI](/openhands/usage/cli/local-gui) | `openhands serve` | Full web GUI | | [IDE Integration](/openhands/usage/cli/ide/overview) | `openhands acp` | Zed, VS Code, JetBrains |