docs: add comprehensive cursor guidelines and rules for development practices (#8401)
* Update cursor rules with specific backend, frontend, docs * Update image example Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * update image example Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Refactor frontend development guidelines: streamline sections, remove outdated icon development instructions, and update checklist for clarity and consistency. --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Gabriel Luiz Freitas Almeida
GitHub
parent
34c55f14b4
commit
ab1ed8ea01
6 changed files with 1670 additions and 17 deletions
440
.cursor/rules/docs_development.mdc
Normal file
440
.cursor/rules/docs_development.mdc
Normal file
|
|
@ -0,0 +1,440 @@
|
|||
---
|
||||
description: "Guidelines for developing and maintaining Langflow documentation using Docusaurus, including content structure, style, and deployment processes."
|
||||
globs:
|
||||
- "docs/**/*.{md,mdx}"
|
||||
- "docs/**/*.{js,jsx,ts,tsx}"
|
||||
- "docs/package*.json"
|
||||
- "docs/docusaurus.config.js"
|
||||
- "docs/sidebars.js"
|
||||
- "docs/static/**/*"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
|
||||
# Documentation Development Guidelines
|
||||
|
||||
## Purpose
|
||||
Guidelines for developing and maintaining Langflow documentation using Docusaurus, including content structure, style, and deployment processes.
|
||||
|
||||
---
|
||||
|
||||
## 1. Documentation Environment Setup
|
||||
|
||||
### Prerequisites
|
||||
- **Node.js:** v22.12 LTS for runtime
|
||||
- **Package Manager:** Yarn for dependency management
|
||||
- **Documentation Framework:** Docusaurus v3
|
||||
|
||||
### Documentation Service
|
||||
```bash
|
||||
cd docs
|
||||
yarn install # Install dependencies
|
||||
yarn start # Start dev server (usually port 3001)
|
||||
```
|
||||
- Auto-reloads on documentation changes
|
||||
- Access at: http://localhost:3001/
|
||||
- Documentation source: `docs/`
|
||||
|
||||
---
|
||||
|
||||
## 2. Documentation Structure
|
||||
|
||||
### Directory Layout
|
||||
```
|
||||
docs/
|
||||
├── docs/ # Main documentation content
|
||||
│ ├── getting-started/ # Getting started guides
|
||||
│ ├── components/ # Component documentation
|
||||
│ ├── integrations/ # Third-party integrations
|
||||
│ ├── administration/ # Admin and deployment guides
|
||||
│ ├── contributing/ # Contribution guidelines
|
||||
│ └── api-reference/ # API documentation
|
||||
├── blog/ # Blog posts and announcements
|
||||
├── src/ # Custom React components
|
||||
├── static/ # Static assets (images, etc.)
|
||||
├── sidebars.js # Sidebar configuration
|
||||
├── docusaurus.config.js # Main configuration
|
||||
└── package.json # Dependencies
|
||||
```
|
||||
|
||||
### Content Types
|
||||
- **Guides:** Step-by-step tutorials (`docs/getting-started/`)
|
||||
- **Reference:** API and component reference (`docs/api-reference/`)
|
||||
- **How-to:** Problem-solving articles (`docs/components/`)
|
||||
- **Concepts:** Explanatory articles about Langflow concepts
|
||||
- **Blog:** Release notes, announcements (`blog/`)
|
||||
|
||||
---
|
||||
|
||||
## 3. Writing Documentation
|
||||
|
||||
### Markdown Conventions
|
||||
```markdown
|
||||
---
|
||||
title: Page Title
|
||||
description: Brief description for SEO
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Page Title
|
||||
|
||||
Brief introduction paragraph.
|
||||
|
||||
## Section Header
|
||||
|
||||
Content with proper formatting.
|
||||
|
||||
### Subsection
|
||||
|
||||
More detailed content.
|
||||
|
||||
:::tip
|
||||
Use admonitions for important information.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Use warnings for potential issues.
|
||||
:::
|
||||
|
||||
:::danger
|
||||
Use danger for critical warnings.
|
||||
:::
|
||||
```
|
||||
|
||||
### Code Blocks
|
||||
````markdown
|
||||
```python title="component_example.py"
|
||||
from langflow.components.base import Component
|
||||
|
||||
class MyComponent(Component):
|
||||
display_name = "My Component"
|
||||
description = "Example component"
|
||||
|
||||
def run(self):
|
||||
return "Hello, World!"
|
||||
```
|
||||
````
|
||||
|
||||
### Images and Assets
|
||||
```markdown
|
||||
<!-- Images go in static/img/ -->
|
||||
|
||||
|
||||
<!-- Use descriptive alt text -->
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Component Documentation
|
||||
|
||||
### Component Page Template
|
||||
```markdown
|
||||
---
|
||||
title: Component Name
|
||||
description: Brief description of what the component does
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Component Name
|
||||
|
||||
Brief overview of the component's purpose.
|
||||
|
||||
## Overview
|
||||
|
||||
What this component does and when to use it.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Inputs
|
||||
|
||||
| Input | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `input_text` | String | Yes | The text to process |
|
||||
| `model_name` | String | No | Model to use (default: gpt-3.5-turbo) |
|
||||
|
||||
### Outputs
|
||||
|
||||
| Output | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `result` | Message | Processed result |
|
||||
|
||||
## Usage Example
|
||||
|
||||
```python
|
||||
# Example of using the component
|
||||
component = MyComponent(
|
||||
input_text="Hello, world!",
|
||||
model_name="gpt-4"
|
||||
)
|
||||
result = component.run()
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Component not loading
|
||||
|
||||
**Solution:** Check that all required inputs are provided.
|
||||
|
||||
### Issue: API key errors
|
||||
|
||||
**Solution:** Ensure your API key is properly configured.
|
||||
```
|
||||
|
||||
### API Documentation
|
||||
```markdown
|
||||
---
|
||||
title: API Endpoint
|
||||
description: REST API endpoint documentation
|
||||
---
|
||||
|
||||
# API Endpoint Name
|
||||
|
||||
## Endpoint
|
||||
|
||||
`POST /api/v1/endpoint`
|
||||
|
||||
## Request
|
||||
|
||||
### Headers
|
||||
```json
|
||||
{
|
||||
"Authorization": "Bearer <token>",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
```
|
||||
|
||||
### Body
|
||||
```json
|
||||
{
|
||||
"parameter": "value",
|
||||
"optional_param": "optional_value"
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success (200)
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"result": "success"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error (400)
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Error message"
|
||||
}
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:7860/api/v1/endpoint \
|
||||
-H "Authorization: Bearer your-token" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"parameter": "value"}'
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Blog Posts and Announcements
|
||||
|
||||
### Blog Post Template
|
||||
```markdown
|
||||
---
|
||||
title: "Release: Langflow v1.1.0"
|
||||
description: "New features and improvements in Langflow v1.1.0"
|
||||
authors: [author-name]
|
||||
date: 2024-01-15
|
||||
tags: [release, features]
|
||||
---
|
||||
|
||||
# Release: Langflow v1.1.0
|
||||
|
||||
Brief introduction to the release.
|
||||
|
||||
## New Features
|
||||
|
||||
### Feature 1
|
||||
Description of the feature and how to use it.
|
||||
|
||||
### Feature 2
|
||||
Another feature description.
|
||||
|
||||
## Improvements
|
||||
|
||||
- List of improvements
|
||||
- Bug fixes
|
||||
- Performance enhancements
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
:::warning
|
||||
List any breaking changes that require user action.
|
||||
:::
|
||||
|
||||
## Migration Guide
|
||||
|
||||
Steps to migrate from previous versions.
|
||||
```
|
||||
|
||||
### Announcement Posts
|
||||
```markdown
|
||||
---
|
||||
title: "Announcement: New Integration"
|
||||
description: "Langflow now supports integration with XYZ service"
|
||||
authors: [author-name]
|
||||
date: 2024-01-15
|
||||
tags: [announcement, integration]
|
||||
---
|
||||
|
||||
Brief announcement content with clear call-to-action.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Configuration
|
||||
|
||||
### Sidebar Configuration (`sidebars.js`)
|
||||
```javascript
|
||||
module.exports = {
|
||||
docs: [
|
||||
'introduction',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Getting Started',
|
||||
items: [
|
||||
'getting-started/installation',
|
||||
'getting-started/quickstart',
|
||||
'getting-started/first-flow',
|
||||
],
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Components',
|
||||
items: [
|
||||
'components/overview',
|
||||
'components/inputs',
|
||||
'components/outputs',
|
||||
'components/processing',
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Site Configuration (`docusaurus.config.js`)
|
||||
```javascript
|
||||
module.exports = {
|
||||
title: 'Langflow Documentation',
|
||||
tagline: 'Build AI flows visually',
|
||||
url: 'https://docs.langflow.org',
|
||||
baseUrl: '/',
|
||||
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
title: 'Langflow',
|
||||
logo: {
|
||||
alt: 'Langflow Logo',
|
||||
src: 'img/logo.svg',
|
||||
},
|
||||
items: [
|
||||
{
|
||||
type: 'doc',
|
||||
docId: 'introduction',
|
||||
position: 'left',
|
||||
label: 'Docs',
|
||||
},
|
||||
{
|
||||
to: '/blog',
|
||||
label: 'Blog',
|
||||
position: 'left'
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Documentation Testing
|
||||
|
||||
### Link Checking
|
||||
```bash
|
||||
# Check for broken internal links
|
||||
yarn build
|
||||
yarn serve
|
||||
# Manual testing or use link checker tools
|
||||
```
|
||||
|
||||
### Content Review
|
||||
- **Accuracy:** Verify all code examples work
|
||||
- **Completeness:** Ensure all features are documented
|
||||
- **Clarity:** Review for clear, concise language
|
||||
- **Navigation:** Test sidebar and cross-references
|
||||
|
||||
### Screenshots
|
||||
- Keep screenshots up-to-date with current UI
|
||||
- Use consistent browser/OS for screenshots
|
||||
- Highlight relevant UI elements
|
||||
- Use descriptive file names
|
||||
|
||||
---
|
||||
|
||||
## 8. Style Guide
|
||||
|
||||
### Writing Style
|
||||
- **Tone:** Professional but approachable
|
||||
- **Voice:** Second person ("you") for instructions
|
||||
- **Tense:** Present tense for current features
|
||||
- **Length:** Keep paragraphs short and scannable
|
||||
|
||||
### Formatting
|
||||
- **Headers:** Use sentence case
|
||||
- **Code:** Inline code with `backticks`
|
||||
- **Emphasis:** Use **bold** for UI elements, *italic* for emphasis
|
||||
- **Lists:** Use parallel structure
|
||||
|
||||
### Terminology
|
||||
- **Langflow:** Always capitalize
|
||||
- **Component:** Capitalize when referring to Langflow components
|
||||
- **Flow:** Capitalize when referring to Langflow flows
|
||||
- **API:** Always uppercase
|
||||
- **JSON:** Always uppercase
|
||||
|
||||
---
|
||||
|
||||
## 9. Deployment
|
||||
|
||||
### Local Testing
|
||||
```bash
|
||||
yarn build # Build static site
|
||||
yarn serve # Serve built site locally
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
- Documentation is automatically deployed on commit to main branch
|
||||
- Build artifacts go to `build/` directory
|
||||
- Static site is served via CDN
|
||||
|
||||
---
|
||||
|
||||
## Documentation Development Checklist
|
||||
- [ ] Documentation service running with `yarn start`
|
||||
- [ ] Content follows markdown conventions
|
||||
- [ ] Code examples are tested and working
|
||||
- [ ] Images have descriptive alt text
|
||||
- [ ] Internal links are functional
|
||||
- [ ] Sidebar navigation is updated
|
||||
- [ ] Content follows style guide
|
||||
- [ ] Screenshots are current and properly formatted
|
||||
- [ ] Cross-references between related topics
|
||||
- [ ] Build succeeds with `yarn build`
|
||||
Loading…
Add table
Add a link
Reference in a new issue