Cursor rule

1 
2---
3description: "Cursor AI rules for Fledge documentation - covers reStructuredText, Sphinx, file naming, and content guidelines"
4globs: 
5  - "docs/**/*"
6  - "*.rst"
7alwaysApply: false
8author: "Ashish Jabble"
9---
10 
11# Documentation Directory Cursor Rules
12 
13## Overview
14This file contains specific rules for working with documentation in the `/docs` directory of the Fledge project. These rules supplement the main project cursor rules and focus on documentation-specific patterns and conventions.
15 
16## Documentation Framework
17- **Format**: reStructuredText (.rst) format exclusively
18- **Build System**: Sphinx documentation generator
19- **Theme**: sphinx_rtd_theme (Read the Docs theme)
20- **Configuration**: All settings in `docs/conf.py`
21 
22## 🚫 "Fledge" Branding Guidelines - MINIMIZE USAGE
23 
24**CRITICAL RULE: Avoid "Fledge" in naming wherever possible**
25 
26### What to Avoid:
27- ❌ Image files: `fledge_architecture.png`
28- ❌ Directory names: `fledge_authentication/`
29- ❌ File names: `fledge_configuration.rst`
30- ❌ Headings: "Fledge Authentication Setup"
31- ❌ Repetitive content: "Fledge does this... Fledge provides that..."
32 
33### What to Use Instead:
34- ✅ Image files: `architecture_overview.png`, `auth_flow.png`
35- ✅ Directory names: `authentication/`, `configuration/`, `monitoring/`
36- ✅ File names: `authentication.rst`, `configuration.rst`
37- ✅ Headings: "Authentication Setup", "Configuration Guide"
38- ✅ Content alternatives: "the platform", "the system", "this feature"
39 
40### When "Fledge" IS Appropriate:
41- Main title pages and introductory content
42- External references and comparisons
43- Installation package names
44- API endpoint references where it's part of the actual name
45 
46## File Organization
47 
48### Directory Structure
49- `/docs/` - Main documentation root
50- `/docs/_static/` - Static assets (CSS, images that aren't content)
51- `/docs/_templates/` - Custom Sphinx templates
52- `/docs/images/` - Documentation images and screenshots
53- `/docs/quick_start/` - Getting started guides
54- `/docs/plugin_developers_guide/` - Plugin development documentation
55- `/docs/rest_api_guide/` - REST API documentation
56- `/docs/building_fledge/` - Build and installation guides
57- `/docs/monitoring/` - System monitoring documentation
58- `/docs/fledge-rule-DataAvailability/` - Built-in Data Availability rule plugin docs
59- `/docs/fledge-rule-Threshold/` - Built-in Threshold rule plugin docs
60- `/docs/fledge-north-OMF.rst` - Built-in OMF north plugin documentation
61- `/docs/keywords/` - Plugin categorization keywords and mappings
62- `/docs/fledge_plugins.rst` - Master plugin list with conditional hyperlinks
63 
64**DIRECTORY NAMING GUIDELINES:**
65- **AVOID "fledge" in new directory names** - use functional descriptions
66- Use topic-based naming: `authentication/` instead of `fledge_authentication/`
67- Keep directory names lowercase with underscores
68- Focus on the purpose/feature rather than product branding
69 
70### File Naming Conventions
71- Use lowercase with underscores: `file_name.rst`
72- Index files: `index.rst` for each directory
73- Numbered files for version/download info: `91_version_history.rst`, `92_downloads.rst`
74- Descriptive names reflecting content: `securing.rst`, `troubleshooting_pi_server_integration.rst`
75- **AVOID "fledge" in filenames** - use functional descriptions: `authentication.rst` instead of `fledge_authentication.rst`
76- Focus on the topic/feature being documented
77 
78## reStructuredText Style Guidelines
79 
80### Heading Hierarchy
81Follow this exact hierarchy for consistency:
82```rst
83***************
84Document Title (Level 1)
85***************
86 
87===============
88Major Section (Level 2)
89===============
90 
91Minor Section (Level 3)
92-----------------------
93 
94Subsection (Level 4)
95^^^^^^^^^^^^^^^^^^^^
96 
97Sub-subsection (Level 5)
98"""""""""""""""""""""""""
99```
100 
101**IMPORTANT NAMING CONVENTIONS:**
102- **AVOID "Fledge" in headings** unless absolutely necessary for context
103- Use descriptive, functional titles: "Authentication Configuration" instead of "Fledge Authentication Configuration"
104- Focus on the feature/functionality rather than the product name
105- Keep headings concise and user-focused
106 
107### Document Structure
1081. **Title**: Use level 1 heading with asterisks above and below
1092. **Introduction**: Brief overview of the document's purpose
1103. **Table of Contents**: Use `.. toctree::` for sections with multiple pages
1114. **Main Content**: Organized with appropriate heading levels
1125. **Cross-references**: Link to related documentation
113 
114### Code Blocks
115```rst
116.. code-block:: language
117   :linenos:
118   :emphasize-lines: 2,3
119 
120   code here
121```
122 
123### Common Directives
124- `.. note::` - Important information
125- `.. warning::` - Critical warnings
126- `.. code-block::` - Code examples
127- `.. image::` - Images with proper alt text
128- `.. toctree::` - Table of contents trees
129 
130### Images and Media
131- Store images in `/docs/images/` directory
132- Use descriptive filenames: `architecture_overview.png` (avoid "fledge_" prefix)
133- **AVOID "Fledge" in image filenames** - use descriptive terms like `architecture_overview.png` instead of `fledge_architecture_overview.png`
134- Always include alt text: `.. image:: images/filename.png :alt: Description`
135- Optimize images for web (reasonable file sizes)
136- Use subdirectories in images/ for organization by topic
137- Keep image names concise and topic-focused
138 
139### Cross-References and Links
140- Internal references: `:doc:`filename`` or `:ref:`label``
141- External links: `Link text <URL>`_
142- API references: Follow existing patterns for REST API documentation
143 
144## Content Guidelines
145 
146### Writing Style
147- Use clear, concise language suitable for technical documentation
148- Write in active voice when possible
149- Use present tense for current functionality
150- Include step-by-step instructions for procedures
151- Provide context and examples
152- **MINIMIZE use of "Fledge" in content** - focus on functionality and features
153- Use "the platform", "the system", or specific feature names instead of repetitive "Fledge" references
154 
155### Code Examples
156- Include complete, runnable examples when possible
157- Show both input and expected output
158- Use realistic data that represents actual Fledge usage
159- Comment code examples appropriately
160- Test code examples to ensure they work
161 
162### API Documentation
163- Document all public APIs, parameters, and return values
164- Include HTTP status codes for REST APIs
165- Provide curl examples for API endpoints
166- Show JSON request/response examples
167- Document error conditions and responses
168 
169### Configuration Documentation
170- Show complete configuration examples
171- Explain all configuration parameters
172- Provide default values where applicable
173- Include configuration validation rules
174- Link to related configuration sections
175 
176## Sphinx Configuration
177 
178### Extensions
179- Keep extensions minimal and focused
180- Document any new extensions added
181- Ensure extensions are available in build environment
182 
183### Build Process
184- Use `make html` for local builds
185- Check for build warnings and errors
186- Test documentation locally before committing
187- Verify all links work correctly
188 
189### Documentation Generation Scripts
190- **Location**: `/scripts/` directory contains documentation generation utilities
191- **Plugin Discovery**: Scripts automatically scan plugin repositories for `docs/` directories
192- **Content Aggregation**: Pulls documentation from external plugin repos during build
193- **Branch Management**: Handles DOCBRANCH parameter for version-specific documentation
194- **Integration**: Merges external plugin docs with core Fledge documentation seamlessly
195 
196### Keywords and Categorization System
197- **Keywords Directory**: `/docs/keywords/` contains category definition files
198- **Category Mapping**: Each keyword file defines a plugin category (e.g., `Augmentation`, `Cleansing`, `Cloud`)
199- **Plugin Keywords**: Plugin repositories contain keyword files that reference category keywords
200- **Automatic Categorization**: Build scripts match plugin keywords with category definitions
201- **Dynamic Organization**: Plugin list automatically organized into categorical sections
202- **Conditional Display**: Categories only appear if plugins with matching keywords exist
203 
204### Version Management
205- Version information managed in `conf.py`
206- DOCBRANCH parameter for plugin documentation
207- Update version info during releases
208 
209### DOCBRANCH System
210- **Purpose**: Generates documentation from both core Fledge and external plugin repositories
211- **Core Documentation**: Always included from the main Fledge repository
212- **Plugin Documentation**: Pulled from individual plugin repositories if they have a `docs/` directory
213- **Branch Control**: Uses `DOCBRANCH='develop'` parameter (set to actual version during releases)
214- **Auto-Discovery**: Only includes plugins that have documentation - ignores repos without `docs/` directory
215- **Generation Scripts**: Located in `/scripts/` directory handle the plugin documentation aggregation
216- **Build Command**: `subprocess.run(["make generated DOCBRANCH='develop'"], shell=True, check=True)` in `conf.py`
217 
218## Plugin Documentation
219 
220### Plugin Repository Documentation
221- **External Plugins**: Each plugin repository can have its own `docs/` directory
222- **Auto-Discovery**: Build system automatically includes plugin docs if `docs/` directory exists
223- **Repository Requirement**: Plugin repos without `docs/` directory are ignored during documentation generation
224- **Branch Synchronization**: Uses same DOCBRANCH parameter as core documentation
225- **Integration**: Plugin docs are seamlessly integrated into the main documentation site
226 
227### Built-in Plugins (In Core Repository)
228The following plugins have documentation included directly in the core Fledge repository:
229- **`fledge-rule-DataAvailability/`** - Data availability rule plugin documentation
230- **`fledge-rule-Threshold/`** - Threshold rule plugin documentation  
231- **`fledge-north-OMF.rst`** - OMF north plugin documentation
232 
233### Plugin Documentation Standards
234- Each plugin should have its own documentation section
235- Follow the pattern established in existing plugin docs
236- Include installation, configuration, and usage instructions
237- Provide troubleshooting sections
238- Use the same reStructuredText format and style guidelines
239 
240### Auto-Generated Content
241- Plugin lists and references may be auto-generated by scripts in `/scripts/` directory
242- Don't manually edit generated content
243- Use the build system's generation capabilities
244- Generated content includes plugin discovery from external repositories
245 
246### Plugin Listing System (`fledge_plugins.rst`)
247- **Master List**: All plugins are listed with name and description in `fledge_plugins.rst`
248- **Smart Hyperlinking**: 
249  - ✅ **With Documentation**: Plugin names become hyperlinks if `docs/` directory exists in plugin repo
250  - ❌ **Without Documentation**: Plugin names remain as plain text (no hyperlink)
251- **Automatic Detection**: Build system checks for documentation availability during generation
252- **Comprehensive Coverage**: Includes all available Fledge plugins regardless of documentation status
253 
254### Plugin Categorization System
255- **Keyword-Based Organization**: Plugins organized by categories using keyword mapping
256- **Keywords Directory**: `/docs/keywords/` contains category definitions and mappings
257- **Plugin Keywords**: Each plugin repository can have a keywords file defining its categories
258- **Categorical Display**: Plugins grouped and displayed under appropriate category sections
259- **Dynamic Categorization**: Categories are automatically generated based on available keywords
260 
261### Plugin Documentation Sources
262- **Core Repository Plugins**: Documentation in `/docs/` for built-in plugins
263- **External Plugin Repos**: Each plugin repository can maintain its own `docs/` directory
264- **Plugin Directory Reference**: All Fledge-based plugins available in main `plugins/` directory
265- **Detailed Documentation**: Comprehensive plugin docs when `docs/` directory exists in plugin repo
266 
267### Plugin Documentation Workflow
2681. **Plugin Discovery**: Build system scans all available Fledge plugin repositories
2692. **Documentation Check**: Determines if plugin repo has `docs/` directory
2703. **List Generation**: All plugins added to `fledge_plugins.rst` with name and description
2714. **Hyperlink Decision**: 
272   - Plugins WITH docs → Name becomes clickable hyperlink
273   - Plugins WITHOUT docs → Name remains as plain text
2745. **Category Organization**: Plugins grouped by keywords into categorical sections
2756. **Integration**: Plugin docs seamlessly integrated into main documentation site
276 
277## Quality Standards
278 
279### Content Review
280- Ensure accuracy of all technical information
281- Verify code examples work with current Fledge version
282- Check that screenshots are current and accurate
283- Review for clarity and completeness
284 
285### Accessibility
286- Use proper heading hierarchy for screen readers
287- Include alt text for all images
288- Ensure good color contrast in custom CSS
289- Test with accessibility tools
290 
291### Maintenance
292- Update documentation when features change
293- Remove or update deprecated information
294- Keep external links current
295- Regular review of troubleshooting sections
296 
297## Build and Deployment
298 
299### Local Testing
300```bash
301cd docs
302make html
303# Check _build/html/index.html in browser
304```
305 
306### Build Warnings
307- Address all Sphinx build warnings
308- Fix broken internal references
309- Verify external links periodically
310- Check image references
311 
312### Dependencies
313- Document build dependencies in `requirements.txt`
314- Keep Sphinx version constraints appropriate
315- Test builds in clean environments
316 
317## Documentation Contribution Guidelines
318 
319### New Documentation
320- Create comprehensive documentation for new features
321- Follow existing patterns and conventions
322- Include in appropriate toctree structures
323- Add cross-references to related content
324 
325### Plugin Documentation Contributions
326- **Adding Plugin Docs**: Create `docs/` directory in plugin repository with proper structure
327- **Hyperlink Generation**: Plugin names in `fledge_plugins.rst` automatically become hyperlinks when docs exist
328- **Keywords Assignment**: Add appropriate keyword files to enable categorical organization
329- **Content Standards**: Follow same reStructuredText standards as core documentation
330- **Testing**: Verify plugin documentation builds correctly with main documentation site
331 
332### Updates
333- Update documentation when code changes
334- Maintain backwards compatibility information
335- Add migration guides for breaking changes
336- Update version history appropriately
337 
338### Review Process
339- Technical accuracy review
340- Editorial review for clarity
341- Build verification
342- Link checking
343 
344## Common Patterns
345 
346### Getting Started Guides
347- Step-by-step instructions
348- Prerequisites clearly stated
349- Expected outcomes described
350- Troubleshooting section included
351 
352### Reference Documentation
353- Comprehensive parameter listings
354- Example configurations
355- Default values documented
356- Related settings cross-referenced
357 
358### Tutorial Content
359- Progressive complexity
360- Complete working examples
361- Clear learning objectives
362- Summary and next steps
363 
364## Troubleshooting Documentation
365 
366### Error Messages
367- Include exact error message text
368- Provide context for when errors occur
369- Give specific resolution steps
370- Link to related configuration
371 
372### Common Issues
373- Document frequently reported problems
374- Provide multiple solution approaches
375- Include preventive measures
376- Reference community resources
377 
378This documentation should be treated as living guidelines that evolve with the project's needs while maintaining consistency and quality standards.
379