List view
# User Story As a professional maintaining multiple CV variants (Data Science, Academic, General), I want a single-source YAML-based system that automatically generates PDF, HTML, and Markdown versions of my CV so that I can maintain consistency across all formats while reducing manual effort and ensuring all platforms (GitHub, websites, job applications) have up-to-date information. ### Business Value: - Reduces CV maintenance time by 75% through single-source updates - Eliminates version inconsistencies across different formats and platforms - Enables automated deployment to GitHub Pages with zero manual intervention - Provides variant-specific customization for different job applications - Supports professional branding consistency across all career platforms ### Acceptance Criteria: 1. System shall generate identical content across PDF, HTML, and Markdown formats from single YAML source 2. System shall support minimum 3 CV variants (Data Science, Academic, General) with selective section inclusion 3. Generated PDF shall maintain professional LaTeX formatting quality with proper typography 4. HTML output shall be responsive and deploy-ready for GitHub Pages 5. Markdown output shall render correctly in GitHub README with proper formatting 6. Build process shall complete in under 60 seconds for all formats 7. System shall validate YAML syntax and provide meaningful error messages 8. Generated files shall follow consistent naming convention: `{variant}_{format}.{ext}` --- ## Repository Structure ``` cv/ ├── data/ │ └── cv_data.yaml # Single source of truth ├── templates/ │ ├── pdf_template.tex # LaTeX template │ ├── html_template.html # HTML template │ └── markdown_template.md # Markdown template └── generators/ │ ├── pdf_generator.py # PDF generation logic │ ├── html_generator.py # HTML generation logic │ └── markdown_generator.py # Markdown generation logic ├── output/ │ ├── datascience_cv.pdf │ ├── datascience_cv.html │ ├── datascience_cv.md │ ├── academic_cv.pdf │ ├── academic_cv.html │ ├── academic_cv.md │ ├── general_cv.pdf │ ├── general_cv.html │ └── general_cv.md ├── .github/ │ └── workflows/ │ └── generate_cv.yml # Automated CI/CD ├── docs/ # GitHub Pages deployment ├── tests/ # Validation and testing ├── README.md ├── pyproject.toml ├── .pre-commit-config.yaml └── .gitignore ``` --- ## Feature 1: YAML Data Structure and Validation As a CV maintainer, I want a comprehensive YAML schema that captures all CV sections with proper validation so that I can confidently update my information without syntax errors. **Background:** The YAML file serves as the single source of truth containing personal information, experience, education, skills, publications, and metadata for different CV variants. ### Complete YAML Schema Implementation Given the CV system requires a structured data source When I create the cv_data.yaml file Then it shall contain the following top-level sections: | Section | Required | Description | | ------------- | -------- | ------------------------- | | personal_info | Yes | Name, contact, links | | profile | Yes | Professional summary | | experience | Yes | Work history array | | education | Yes | Academic background | | skills | Yes | Technical and soft skills | | publications | No | Research publications | | projects | No | Notable projects | | awards | No | Recognition and honors | | metadata | Yes | Variant configurations | And each experience entry shall include: | Field | Type | Required | Example | | ------------ | ------- | -------- | ------------------------ | | title | string | Yes | "Data Scientist" | | company | string | Yes | "HelicoBio" | | location | string | Yes | "New Zealand" | | start_date | string | Yes | "Aug 2021" | | end_date | string | No | "Aug 2023" | | current | boolean | No | false | | description | string | Yes | Role summary | | achievements | array | No | Bulleted accomplishments | | variants (tags) | array | Yes | ["ds", "ac", "general"] | And metadata shall define variant configurations: | Variant | Sections Included | Target Audience | | ------- | ------------------------------- | -------------------- | | ds | experience, skills, projects | Data Science roles | | ac | education, publications, awards | Academic positions | | general | experience, education, skills | General applications | **Estimated Complexity:** Medium ### YAML Validation and Error Handling Given the cv_data.yaml file exists When I run the validation process Then the system shall check for: - Valid YAML syntax with meaningful line-specific error messages - Required fields presence for each section - Date format consistency (MMM YYYY pattern) - Email format validation for contact information - URL format validation for links and websites - Variant tag validity against predefined list And when validation fails Then the system shall: - Display specific error location (line number, field name) - Suggest correction for common mistakes - Exit with non-zero status code - Log errors to validation.log file And when validation succeeds Then the system shall: - Display "YAML validation passed" message - Proceed to template processing - Log success with timestamp **Estimated Complexity:** Medium **Technical Details:** - Use Python's `pyyaml`, `pydantic` and `jsonschema` libraries for validation - Implement custom validators for date formats and professional domains - Generate schema.json from Python dataclasses for consistency --- ## Feature 2: Template Engine and Format Generation As a CV maintainer, I want flexible Jinja2 templates for each output format so that I can customize styling and layout while maintaining content consistency. **Background:** The template engine processes YAML data through format-specific templates to generate PDF (via LaTeX), HTML, and Markdown outputs with professional formatting. ### LaTeX Template Processing Given the validated YAML data and LaTeX template exist When I generate the PDF version for "ds" variant Then the system shall: - Load latex_template.tex with Jinja2 syntax - Filter sections based on variant configuration - Process personal_info into header with proper escaping - Render experience section with date formatting - Apply LaTeX formatting for lists and achievements - Generate intermediate .tex file in output/latex/ directory - Execute pdflatex compilation with error handling - Produce final PDF in `output/cv_ds.pdf` And the LaTeX template shall support: | Element | LaTeX Command | Styling | | --------------- | ------------- | ------------------ | | Section headers | \section{} | Bold, large font | | Subsections | \subsection{} | Medium font | | Date ranges | Custom macro | Right-aligned | | Bullet points | \itemize | Consistent spacing | | Contact info | \href{} | Clickable links | And compilation shall handle: - Special character escaping (&, %, $, #) - Unicode character support - Bibliography processing for publications - Multiple compilation passes for references **Estimated Complexity:** High ### HTML Template with Responsive Design Given the validated YAML data and HTML template exist When I generate the HTML version for any variant Then the system shall: - Process html_template.html with embedded CSS - Generate responsive layout with mobile-first approach - Include meta tags for social media sharing - Apply semantic HTML5 structure - Render skills as progress bars or badges - Format dates consistently across all sections - Include print-friendly CSS media queries - Output to `output/{variant}_cv.html` And the HTML output shall be: - W3C HTML5 compliant - Responsive across devices (320px to 2560px width) - Accessible (WCAG 2.1 AA compliant) - SEO optimized with proper meta tags - Print-friendly with appropriate page breaks And styling shall include: - Professional color scheme (#2c3e50, #3498db, #ecf0f1) - Typography hierarchy with system fonts - Consistent spacing using CSS Grid/Flexbox - Hover effects for interactive elements - PDF download button integration **Estimated Complexity:** Medium ### Markdown Generation for GitHub Given the validated YAML data and Markdown template exist When I generate the Markdown version Then the system shall: - Process markdown_template.md with GitHub-specific syntax - Generate table of contents with anchor links - Format skills as badge-style images - Convert URLs to clickable links - Apply consistent heading hierarchy - Include shields.io badges for technologies - Format publications with proper citations - Output to `output/cv.md` And the Markdown shall include: - GitHub-flavored markdown syntax - Emoji integration for visual appeal - Table formatting for structured data - Code block highlighting for technical skills - Collapsible sections for detailed information Example output structure: ```markdown # Edison Florez **Data Scientist | Business Analyst | Computational Physicist** 📧 [email protected] • 🔗 [GitHub](github.com/e-florez) • 💼 [LinkedIn](linkedin.com/in/edisonflorez) ## 🎯 Profile [Profile text from YAML] ## 💼 Professional Experience ### Data Scientist - HelicoBio (Aug 2021 - Aug 2023) [Formatted experience details] ``` **Estimated Complexity:** Low **Technical Details:** - Implement Jinja2 custom filters for date formatting, text escaping, and URL generation - Use `weasyprint` for HTML to PDF conversion as LaTeX alternative - Store templates in version control with clear documentation - Support template inheritance for common elements --- ## Feature 3: Build Orchestration and Automation As a CV maintainer, I want a single command that generates all formats and variants (tags) so that I can quickly update all my CV versions without manual intervention. **Background:** The build system coordinates validation, template processing, compilation, and deployment through a unified interface with comprehensive error handling. ### Command-Line Interface Given the CV system is properly installed When I execute the build command Then I shall be able to use the following syntax: python generate.py [options] With the following options: | Option | Short | Description | Default | | --------------- | ----- | ------------------------- | ------------- | | --tags | -t | Comma-separated tags | "all" | | --formats | -f | Comma-separated formats | "all" | | --output-dir | -o | Output directory | "./output" | | --clean | -c | Clean output before build | False | | --validate-only | -V | Only validate YAML | False | | --verbose | -v | Verbose logging | False | | --config | -cgf | Custom config file | "config.yaml" | Examples: python generate.py --tags ds,ac --formats pdf,html python generate.py --clean --verbose python generate.py --validate-only **Estimated Complexity:** Low ### Build Process Orchestration Given valid command-line arguments When I execute the build process Then the system shall: 1. Initialize logging with timestamp and level 2. Load and validate configuration files 3. Parse and validate cv_data.yaml 4. Create output directory structure 5. Process each variant-format combination 6. Generate build summary report (save) 7. Clean temporary files 8. Exit with appropriate status code And for each variant-format combination: | Step | Action | Error Handling | | ---- | ---------------------- | ------------------------ | | 1 | Load template | Fail with template error | | 2 | Filter data by variant | Continue with warning | | 3 | Render template | Fail with syntax error | | 4 | Compile/process output | Retry once, then fail | | 5 | Validate output | Warn but continue | And the build summary shall include: - Total build time - Success/failure count per format - File sizes of generated outputs - Warning and error summaries - Next steps or recommendations **Estimated Complexity:** Medium ### GitHub Actions Integration Given the CV repository exists on GitHub When I push changes to the main branch Then the GitHub Action shall: - Trigger on push to main branch and pull requests - Set up Python 3.9+ environment - Install LaTeX distribution (TeX Live) - Install Python dependencies from `pyproject.toml` - Run YAML validation - Generate all CV variants (tags) and formats - Deploy HTML version to GitHub Pages - Create release artifacts for PDF downloads - Send notification on build failure And the workflow file (.github/workflows/cv-build.yml) shall: - Complete build in under 5 minutes - Cache LaTeX packages for faster builds - Upload build artifacts with 90-day retention - Tag releases with semantic versioning - Support manual workflow dispatch - Include build status badge for README **Estimated Complexity:** Medium **Technical Details:** - Implement parallel processing for multiple variant-format combinations - Use `concurrent.futures` for async template processing - Integrate with GitHub CLI for automated releases - Support dry-run mode for testing builds --- ## Feature 4: Configuration Management and Customization As a CV maintainer, I want flexible configuration options that allow me to customize styling, content selection, and output behavior so that I can adapt the system to different requirements without modifying core code. **Background:** Configuration management enables customization of templates, styling, content filtering, and build behavior through external configuration files. ### Variant Configuration System Given the need for different CV variants When I define variant (tags) configurations Then each variant (tags) shall be defined in `configs/{variant}_profile.yaml` with: | Configuration | Type | Description | Example | | ------------- | ------ | ---------------------- | -------------------------------- | | name | string | Display name | "Data Science Profile" | | description | string | Purpose description | "For data science positions" | | sections | array | Included sections | ["experience", "skills"] | | section_order | array | Display order | ["profile", "experience"] | | filters | object | Content filters | {"experience": {"min_years": 2}} | | styling | object | Format-specific styles | {"latex": {"color": "blue"}} | | metadata | object | Additional settings | {"show_references": false} | And content filtering shall support: - Date range filtering (after/before dates) - Tag-based inclusion/exclusion - Keyword matching in descriptions - Minimum relevance scoring - Custom boolean expressions Example ds_profile.yaml: ```yaml name: "Data Science Profile" description: "Optimized for data science and analytics positions" sections: - profile - experience - skills - projects - education filters: experience: tags_include: ["data-science", "python", "machine-learning"] min_relevance: 0.7 projects: tags_include: ["data", "analytics", "ml"] styling: latex: primary_color: "blue" font_family: "modern" html: theme: "tech" show_progress_bars: true ``` **Estimated Complexity:** High ### Template Customization Framework Given the need for flexible template customization When I create custom templates Then the system shall support: - Template inheritance with base templates - Custom Jinja2 filters and functions - Conditional section rendering - Dynamic styling based on variant - Multi-language support - Custom field mappings And custom filters shall include: | Filter | Purpose | Example Usage | | -------------- | ------------------- | ------------------------------------------- | | format_date | Date formatting | {{ start_date \| format_date('MMM YYYY') }} | | latex_escape | LaTeX escaping | {{ description \| latex_escape }} | | markdown_links | Link formatting | {{ url \| markdown_links }} | | skill_level | Skill visualization | {{ skill \| skill_level('bar') }} | | truncate_words | Text truncation | {{ text \| truncate_words(50) }} | And template variables shall include: - build_timestamp: Generation timestamp - variant_config: Current variant settings - total_experience: Calculated experience years - skill_categories: Grouped skills - contact_formatted: Formatted contact info **Estimated Complexity:** Medium **Technical Details:** - Implement plugin architecture for custom filters - Support SCSS preprocessing for CSS generation - Enable template hot-reloading during development - Validate template syntax before builds --- ## Out of Scope: - Advanced analytics or tracking of CV performance - Integration with job application platforms or ATS systems - AI-powered content suggestions or optimization - Integration with external data sources (LinkedIn, ORCID) - Advanced typography features beyond standard LaTeX packages - Custom PDF form fields or interactive elements - Automated grammar checking or content validation ## Additional Notes: - **Performance Considerations:** Build process should complete in under 60 seconds for typical CV content; consider implementing incremental builds for large datasets - **Architecture Recommendations:** Use factory pattern for format generators; implement observer pattern for build notifications; consider using Docker for consistent LaTeX environments - **Configuration Management:** Store sensitive information (API keys, personal data) in environment variables; use configuration validation schemas - **Template Security:** Sanitize all user inputs in templates; use safe Jinja2 evaluation modes; validate template syntax before execution - **Dependency Management:** Pin specific versions of LaTeX packages; use virtual environments for Python dependencies; document system requirements clearly - **Error Recovery:** Implement graceful degradation when optional dependencies are missing; provide clear installation instructions for LaTeX distributions - **Future Extensibility:** Design plugin architecture for additional output formats; support custom field types; enable third-party template repositories ## Labels: - career-tools - document-generation - automation - yaml-processing - multi-format-output - template-engine - continuous-integration - personal-branding --- **Priority:** High **Estimated Complexity:** High
Overdue by 4 month(s)•Due by June 9, 2025