grabowski
c86266fd38
- 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
91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
# /docs/datasheets
|
|
|
|
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
|