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,90 @@
|
||||
# /docs/datasheets
|
||||
|
||||
Datasheets for key components.
|
||||
Component datasheets and technical specifications.
|
||||
|
||||
## Purpose
|
||||
This directory contains datasheets for all components used in the project, providing essential technical information for design, assembly, and troubleshooting.
|
||||
|
||||
## File Organization
|
||||
Datasheets should be organized by component type or manufacturer for easy reference:
|
||||
|
||||
```
|
||||
datasheets/
|
||||
├── microcontrollers/
|
||||
│ ├── DS_STM32F401_datasheet_v1.0.0_2024-08-11.pdf
|
||||
│ └── DS_ESP32_datasheet_v2.1.0_2024-08-11.pdf
|
||||
├── power-management/
|
||||
│ ├── DS_AMS1117_voltage-regulator_2024-08-11.pdf
|
||||
│ └── DS_LM2596_switching-regulator_2024-08-11.pdf
|
||||
├── sensors/
|
||||
│ ├── DS_BME280_environmental-sensor_2024-08-11.pdf
|
||||
│ └── DS_MPU6050_imu-sensor_2024-08-11.pdf
|
||||
├── connectors/
|
||||
│ ├── DS_USB-C_receptacle_2024-08-11.pdf
|
||||
│ └── DS_JST-XH_connector-series_2024-08-11.pdf
|
||||
└── passive-components/
|
||||
├── DS_Yageo_resistor-series_2024-08-11.pdf
|
||||
└── DS_Murata_capacitor-series_2024-08-11.pdf
|
||||
```
|
||||
|
||||
## CI Auto-Sort System
|
||||
To enable automatic organization by CI bots, use the **DS_** prefix for all datasheet files:
|
||||
|
||||
### Naming Convention
|
||||
```
|
||||
DS_[component-name]_[description]_[version]_[date].pdf
|
||||
```
|
||||
|
||||
### Examples
|
||||
```
|
||||
DS_STM32F401_datasheet_v1.0.0_2024-08-11.pdf
|
||||
DS_LM358_operational-amplifier_2024-08-11.pdf
|
||||
DS_USB-C_receptacle-specification_2024-08-11.pdf
|
||||
DS_Yageo_resistor-series-RC_2024-08-11.pdf
|
||||
```
|
||||
|
||||
### How It Works
|
||||
1. **Upload anywhere**: Place datasheet files with DS_ prefix anywhere in the project
|
||||
2. **CI detection**: CI bot automatically detects files starting with DS_
|
||||
3. **Auto-move**: Files are automatically moved to `docs/datasheets/` directory
|
||||
4. **Organization**: Files can be further organized into subdirectories manually or by additional CI rules
|
||||
|
||||
## File Types
|
||||
- **PDF**: Primary format for datasheets (preferred)
|
||||
- **HTML**: Web-based datasheets (save as PDF when possible)
|
||||
- **DOC/DOCX**: Microsoft Word documents (convert to PDF)
|
||||
- **TXT**: Plain text specifications (minimal use)
|
||||
|
||||
## Best Practices
|
||||
- **Always use DS_ prefix** for automatic CI sorting
|
||||
- **Include version numbers** when available from manufacturer
|
||||
- **Use descriptive names** that identify the component clearly
|
||||
- **Download official datasheets** directly from manufacturer websites
|
||||
- **Keep original filenames** when possible, but add DS_ prefix
|
||||
- **Include date** when datasheet was downloaded/updated
|
||||
- **Verify accuracy** - ensure datasheet matches actual component used
|
||||
|
||||
## Datasheet Sources
|
||||
- **Manufacturer websites**: Primary source for official datasheets
|
||||
- **Distributor sites**: Digi-Key, Mouser, LCSC often have datasheets
|
||||
- **Component databases**: Octopart, Findchips for cross-referencing
|
||||
- **Avoid unofficial sources**: Use only verified manufacturer data
|
||||
|
||||
## Integration with BOM
|
||||
Datasheets should correspond to components in your BOM:
|
||||
- Reference the datasheet URL in BOM files
|
||||
- Ensure part numbers match between BOM and datasheets
|
||||
- Include datasheet links in component selection documentation
|
||||
- Use datasheets to verify component specifications during design
|
||||
|
||||
## Version Control
|
||||
- **Commit datasheets** with design files for complete project history
|
||||
- **Tag important versions** when component specifications change
|
||||
- **Document changes** when updating to newer datasheet versions
|
||||
- **Maintain traceability** between design decisions and datasheet specifications
|
||||
|
||||
## File Size Considerations
|
||||
- **Compress large files** when possible without losing quality
|
||||
- **Split large documents** into relevant sections if needed
|
||||
- **Use Git LFS** for very large files (>100MB) if necessary
|
||||
- **Consider external links** for extremely large manufacturer documents
|
||||
|
||||
@@ -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