Skip to content

fix: Align Example Content and Dependencies #30

@aygp-dr

Description

@aygp-dr

Example Content and Dependencies Alignment Issues\n\n## Content Organization\n\n1. Header Consistency\n- 04-embeddings-intro.org uses custom properties\n- 05-photo-embeddings.org uses common-headers.org\n- Other examples need to be checked for consistency\n\n2. Dependencies Management\n- Examples have implicit dependencies (e.g., jq, curl)\n- No clear documentation of required tools\n- No validation in Makefile for required dependencies\n\n3. File Path Handling\n- Inconsistent use of relative paths vs projectile-project-root\n- Some examples use ../data while others use absolute paths\n- No standard way to handle file paths across examples\n\n4. Results Directory Structure\n- Some examples write to ../data directly\n- Others use specific subdirectories\n- No clear pattern for output organization\n\n## Proposed Changes\n\n1. Standardize Headers\n- Use common-headers.org consistently\n- Document header requirements\n- Validate headers in CI\n\n2. Document Dependencies\n- Create dependencies.md listing all required tools\n- Add dependency checks to Makefile\n- Include installation instructions\n\n3. Standardize Path Handling\n- Use consistent path resolution method\n- Document path conventions\n- Add helper functions for path handling\n\n4. Organize Output Structure\n- Create standard subdirectories in data/\n- Document directory purposes\n- Add cleanup utilities\n\n## Implementation Tasks\n\n1. Update all example files to use common headers\n2. Add dependency validation to init target\n3. Create path handling utilities\n4. Restructure data directory\n5. Update documentation\n\n## Success Criteria\n- All examples use consistent header format\n- Dependencies are clearly documented and validated\n- File paths follow consistent pattern\n- Output files are organized in standard structure

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestneeds-reviewRequires review from maintainers

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions