Add CI auto-sort system for datasheets and images
- Add DS_ prefix for datasheets - automatically moved to docs/datasheets/ - Add IMG_ prefix for images - automatically moved to docs/images/ - Update FILE-NAMING-AND-VERSIONING.md with CI auto-sort prefix examples - Create comprehensive docs/datasheets/README.md with CI auto-sort documentation - Create comprehensive docs/images/README.md with CI auto-sort documentation - Add ci/auto-sort-files.yml GitHub Actions workflow for automatic file organization - Update ci/README.md with complete auto-sort system documentation - Update main README.md to reference CI auto-sort system - Enable users to upload files anywhere with correct prefix for automatic organization - Support multiple file types: PDF, DOC, PNG, JPG, SVG, etc. - Provide complete CI workflow with commit automation and error handling
This commit is contained in:
@@ -1,3 +1,154 @@
|
||||
# /docs/images
|
||||
|
||||
Diagrams, photos, and figures.
|
||||
Documentation images, diagrams, photos, and figures.
|
||||
|
||||
## Purpose
|
||||
This directory contains all visual documentation for the project including diagrams, photos, screenshots, and illustrations used in documentation, assembly guides, and technical references.
|
||||
|
||||
## File Organization
|
||||
Images should be organized by type and purpose for easy reference:
|
||||
|
||||
```
|
||||
images/
|
||||
├── schematics/
|
||||
│ ├── IMG_schematic-block-diagram_v1.0.0_2024-08-11.svg
|
||||
│ ├── IMG_power-supply-schematic_v1.2.0_2024-08-11.png
|
||||
│ └── IMG_signal-flow-diagram_v2.0.0_2024-08-11.pdf
|
||||
├── pcb-layouts/
|
||||
│ ├── IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png
|
||||
│ ├── IMG_pcb-layout_bottom-view_v1.0.0_2024-08-11.png
|
||||
│ └── IMG_pcb-3d-render_assembled_v1.0.0_2024-08-11.jpg
|
||||
├── assembly/
|
||||
│ ├── IMG_assembly-photo_step-1_2024-08-11.jpg
|
||||
│ ├── IMG_assembly-photo_step-2_2024-08-11.jpg
|
||||
│ └── IMG_assembly-diagram_exploded-view_2024-08-11.png
|
||||
├── mechanical/
|
||||
│ ├── IMG_enclosure-design_front-view_v2.0.0_2024-08-11.png
|
||||
│ ├── IMG_mounting-bracket_dimensions_v1.1.0_2024-08-11.pdf
|
||||
│ └── IMG_mechanical-assembly_3d-view_v1.0.0_2024-08-11.jpg
|
||||
├── testing/
|
||||
│ ├── IMG_test-setup_functional_2024-08-11.jpg
|
||||
│ ├── IMG_oscilloscope-capture_signal-analysis_2024-08-11.png
|
||||
│ └── IMG_measurement-results_performance_2024-08-11.png
|
||||
└── user-interface/
|
||||
├── IMG_gui-screenshot_main-window_v1.0.0_2024-08-11.png
|
||||
├── IMG_display-layout_status-screen_v1.0.0_2024-08-11.jpg
|
||||
└── IMG_control-panel_button-layout_2024-08-11.png
|
||||
```
|
||||
|
||||
## CI Auto-Sort System
|
||||
To enable automatic organization by CI bots, use the **IMG_** prefix for all image files:
|
||||
|
||||
### Naming Convention
|
||||
```
|
||||
IMG_[subject]_[description]_[version]_[date].extension
|
||||
```
|
||||
|
||||
### Examples
|
||||
```
|
||||
IMG_pcb-layout_top-view_v1.0.0_2024-08-11.png
|
||||
IMG_assembly-photo_step-3_2024-08-11.jpg
|
||||
IMG_schematic-block-diagram_v2.1.0_2024-08-11.svg
|
||||
IMG_test-results_frequency-response_2024-08-11.png
|
||||
IMG_enclosure-design_front-panel_v1.2.0_2024-08-11.pdf
|
||||
```
|
||||
|
||||
### How It Works
|
||||
1. **Upload anywhere**: Place image files with IMG_ prefix anywhere in the project
|
||||
2. **CI detection**: CI bot automatically detects files starting with IMG_
|
||||
3. **Auto-move**: Files are automatically moved to `docs/images/` directory
|
||||
4. **Organization**: Files can be further organized into subdirectories manually or by additional CI rules
|
||||
|
||||
## Supported File Types
|
||||
- **PNG**: Preferred for diagrams, screenshots, and technical illustrations
|
||||
- **JPG/JPEG**: Best for photographs and complex images
|
||||
- **SVG**: Vector graphics for scalable diagrams and schematics
|
||||
- **PDF**: Vector documents and technical drawings
|
||||
- **GIF**: Animated demonstrations (use sparingly)
|
||||
- **WEBP**: Modern format for web optimization (when supported)
|
||||
|
||||
## Image Categories
|
||||
|
||||
### Schematic Diagrams
|
||||
- Block diagrams showing system architecture
|
||||
- Circuit schematics and sub-circuits
|
||||
- Signal flow and timing diagrams
|
||||
- Electrical connection diagrams
|
||||
|
||||
### PCB and Layout Images
|
||||
- PCB layout views (top, bottom, internal layers)
|
||||
- 3D renderings of assembled boards
|
||||
- Component placement diagrams
|
||||
- Routing and trace illustrations
|
||||
|
||||
### Assembly Documentation
|
||||
- Step-by-step assembly photos
|
||||
- Component identification images
|
||||
- Tool and equipment photos
|
||||
- Before/after assembly comparisons
|
||||
|
||||
### Mechanical Designs
|
||||
- CAD renderings and technical drawings
|
||||
- Enclosure and housing designs
|
||||
- Mounting and installation diagrams
|
||||
- Dimensional drawings and specifications
|
||||
|
||||
### Testing and Validation
|
||||
- Test setup photographs
|
||||
- Oscilloscope captures and measurements
|
||||
- Performance graphs and charts
|
||||
- Compliance testing results
|
||||
|
||||
### User Interface
|
||||
- GUI screenshots and mockups
|
||||
- Display layouts and screen designs
|
||||
- Control panel and button layouts
|
||||
- User interaction flows
|
||||
|
||||
## Best Practices
|
||||
- **Always use IMG_ prefix** for automatic CI sorting
|
||||
- **Use descriptive names** that clearly identify the image content
|
||||
- **Include version numbers** for design-related images
|
||||
- **Optimize file sizes** without compromising quality
|
||||
- **Use appropriate formats** (PNG for diagrams, JPG for photos)
|
||||
- **Include date** when image was created or captured
|
||||
- **Maintain consistent naming** across related images
|
||||
- **Document image sources** and creation methods
|
||||
|
||||
## Image Quality Guidelines
|
||||
- **Resolution**: Use appropriate resolution for intended use
|
||||
- Screenshots: Native resolution or 1920x1080 max
|
||||
- Photos: 1920x1080 to 4K depending on detail needed
|
||||
- Diagrams: Vector format (SVG) when possible
|
||||
- **Compression**: Balance file size with quality
|
||||
- **Color space**: Use sRGB for web compatibility
|
||||
- **File size**: Keep under 5MB per image when possible
|
||||
|
||||
## Creation Tools
|
||||
- **Screenshots**: Built-in OS tools, Greenshot, LightShot
|
||||
- **Diagrams**: Draw.io, Lucidchart, Visio, Inkscape
|
||||
- **Photo editing**: GIMP, Photoshop, Paint.NET
|
||||
- **CAD renders**: KiCad 3D viewer, FreeCAD, SolidWorks
|
||||
- **Vector graphics**: Inkscape, Illustrator, SVG editors
|
||||
|
||||
## Integration with Documentation
|
||||
Images should be referenced in documentation:
|
||||
- Use relative paths in markdown: ``
|
||||
- Include alt text for accessibility
|
||||
- Reference images by filename in assembly guides
|
||||
- Maintain links when reorganizing files
|
||||
- Update documentation when images are updated
|
||||
|
||||
## Version Control
|
||||
- **Commit images** with related design changes
|
||||
- **Use Git LFS** for large image files (>10MB)
|
||||
- **Tag versions** when images represent specific design iterations
|
||||
- **Document changes** when updating existing images
|
||||
- **Maintain history** of design evolution through images
|
||||
|
||||
## File Size Management
|
||||
- **Optimize images** before committing to reduce repository size
|
||||
- **Use appropriate compression** for different image types
|
||||
- **Consider external hosting** for very large images
|
||||
- **Regular cleanup** of outdated or unused images
|
||||
- **Monitor repository size** and use Git LFS when necessary
|
||||
|
||||
Reference in New Issue
Block a user